GitHub - zqiren/Orbital: Give your agents a project, not a prompt

English · 简体中文

You give your agent the work. It reads everything the project already knows, does it, and writes back what it learned.

The agent that never starts from zero.

Every piece of work your agent finishes becomes context for the next instruction.
The project gets more capable the longer it runs — not reset to zero.

Windows Installer (.exe)  ·  macOS Installer (.dmg)  ·  Watch the demo

Set up in under 5 minutes. No Python or Node required.

Why this exists

Every agent today forgets. You paste the same context into every session. You re-explain the project every morning. The decisions you settled last week vanish when the session ends, so you settle them again.

Your agent dies. Your session ends. Your work doesn't.

Orbital is an agent built around that fact. Everything it finishes — the artifacts it produced, the decisions, the lessons — is written into the project and read back at the start of the next session. Instead of starting from zero, your agent starts from everything it has already made. The work compounds.

What makes Orbital different

Artifacts that compound. Most of the work in a project is your agent producing artifacts — code, documents, research, reports. Every artifact it finishes becomes reference material for the next session and the next artifact, alongside the state, decisions, and lessons it keeps current. A project you opened yesterday knows what happened yesterday — and builds on it.

Grounded in your real work. The project is a folder on your disk, local-first. Your files aren't just storage — they're what your agent reads before it produces anything, so its artifacts target your actual codebase, your actual documents, your actual data, instead of plausible-sounding output grounded in nothing.

Swap the hands, keep the memory. Your agent delegates execution to sub-agents — Claude Code, Codex, Gemini CLI, or any CLI agent. They're interchangeable: each one works from the same accumulated context — the same files, decisions, instructions, and history — and what they finish flows back into the project. Change the sub-agent; lose nothing.

Safe to leave running. Queue up tasks and walk away: your agent works through them one at a time, declaring an outcome on every item — completed with a summary, or blocked with a reason for you to resolve. It works inside sandbox boundaries you set, under a per-project budget, with approval rules you control.

At a Glance

• Persistent context — PROJECT_STATE.md, DECISIONS.md, LESSONS.md maintained across sessions, so each session starts from everything the last one finished
• Project-based agent management — each project is a folder with its own workspace, instructions, budget, and autonomy level
• Sub-agent delegation — the management agent monitors your workspace, evaluates progress against goals, and dispatches work to Claude Code, Codex, Gemini CLI, or any CLI agent — all reading the same accumulated context
• Self-improving skills — agent creates reusable skills from multi-step workflows and consults them before repeating similar tasks
• Task queue — queue work per project and walk away; the agent drains items one at a time, marking each completed (with a summary) or blocked (with a reason); pause mid-queue to chat and steer, then resume
• Triggers — set up a cron job or file watcher so the management agent checks in regularly and kicks off sub-agents without you
• 13 built-in LLM providers — Anthropic, OpenAI, DeepSeek, Moonshot (Kimi), Groq, Google Gemini, xAI, Mistral, Together, OpenRouter, Zhipu, Qwen, plus custom endpoints
• Browser automation — 26 browser actions via Patchright with anti-detection
• Credential store — API keys and website passwords in OS keychain, never exposed to chat
• Sandboxed execution — agents only access folders you specify (Windows sandbox user, macOS Seatbelt)
• Approval workflows — agents pause before risky actions; approve from desktop or phone
• Budget controls — per-project spending limits with configurable actions
• Mobile supervision — manage agents from your phone via QR code pairing

Quick Start

1. Launch Orbital — the setup wizard guides you through three steps:

   Step 1 — LLM Provider: Connect your API key. Supports Anthropic, OpenAI, Moonshot, DeepSeek, and a dozen other providers.

   

   Step 2 — Sandbox: Orbital creates an isolated user account so agents can't access your personal files or network without permission.

   

   Step 3 — Browser Warm-up: Sign into sites your agents will need (Google, GitHub, etc.) so they can browse without getting blocked by CAPTCHAs.

   

2. Create a project — give it a name, pick a workspace directory, set an autonomy level

3. Chat — type a task in the chat bar and the management agent handles it
4. Walk away — queue the next tasks; each finished one becomes context the next builds on

See it compound

The project keeps its own state, decisions, and lessons current — written by the agent, read back every session.

Delegate to Claude Code, Codex, or Gemini — each works from the same accumulated context, and what they finish flows back in.

How It Works

Orbital is one agent bound to a project — not a chat session. The project binds a workspace directory, evolving instructions, an autonomy preset, a budget, approval rules, and persistent state into one supervised unit. Your agent plans and delegates inside it, sub-agents execute, and everything they finish is written back as context for the next instruction. You supervise from anywhere.

flowchart TB
    UI["<b>Frontend (React SPA)</b><br/>Chat UI · Approval Cards · Settings · Files"]

    subgraph daemon["Daemon (FastAPI + uvicorn)"]
        direction TB
        AM["AgentManager<br/><i>lifecycle</i>"]
        SAM["SubAgentManager<br/><i>delegation</i>"]
        TM["TriggerManager<br/><i>cron · file watch</i>"]
        Loop["Agent Loop<br/><i>streaming · safety guards</i>"]
        TR["Transports<br/>Pipe · PTY · SDK · ACP"]
        LLM["LLM Provider<br/><i>OpenAI + Anthropic SDK</i>"]
        Tools["Tool Registry<br/><i>shell · file · browser · triggers</i>"]
        Auto["Autonomy Interceptor<br/><i>approve · deny · bypass</i>"]

        AM --> Loop
        SAM --> TR
        TM --> AM
        Loop --> LLM
        Loop --> Tools
        Loop --> Auto
    end

    Platform["<b>Platform Layer</b><br/>Windows sandbox user · macOS Seatbelt · Linux bubblewrap (planned)"]
    Relay["<b>Cloud Relay (Node.js, optional)</b><br/>REST proxy · Event forwarding · Push notifications · Pairing"]
    Phone["Phone"]

    UI <-->|REST + WS| AM
    UI <-->|REST + WS| SAM
    Tools --> Platform
    AM -.WebSocket tunnel.-> Relay
    Relay -.WebSocket.-> Phone

Key design decisions:

• Memory is the product: the agent maintains structured project state (state, decisions, lessons, session log) and re-reads it every session — the work compounds instead of resetting
• Isolation: OS-level sandboxing (Windows sandbox user, macOS Seatbelt, Linux bubblewrap planned)
• Fail-closed interceptor: Any approval system error results in DENY, never ALLOW
• Single daemon: PID file enforcement prevents multiple instances
• Local-first: Your files and project state live on your disk. The cloud relay, when enabled, proxies approvals and events — not your files.

How Orbital compares

The short version: Claude Projects proved the mental model. OpenClaw proved local agents work. Cowork proved people want agents to run autonomously. Orbital is one agent that does all three on your machine — it keeps its own project state current across sessions, and delegates execution to whichever sub-agents you choose. It never starts from zero.

Feature Deep Dives

How the work compounds

{workspace}/
+-- orbital/                            # Operational metadata
    +-- sessions/
    |   +-- {session_id}.jsonl          # Append-only session log
    +-- instructions/
    |   +-- project_goals.md
    |   +-- user_directives.md
    +-- skills/                         # Project skills
    +-- sub_agents/                     # Sub-agent transcripts
    +-- tool-results/                   # Tool output artifacts
    +-- output/                         # Agent work artifacts
    |   +-- screenshots/                # Browser screenshots
    |   +-- pdfs/                       # Saved PDFs
    |   +-- shell-output/               # Shell command output
    +-- PROJECT_STATE.md                # Current task state
    +-- DECISIONS.md                    # Decision log
    +-- LESSONS.md                      # Learned patterns
    +-- SESSION_LOG.md                  # Last 3 session summaries
    +-- CONTEXT.md                      # External reference material

~/orbital/                              # Home global (daemon infrastructure)
+-- daemon.pid                          # Singleton enforcement
+-- device.json                         # Device identity
+-- browser-profile/                    # Shared browser profile
+-- credential-meta.json                # Credential metadata

Tools & execution

Control & safety

Installation

Windows

1. Download Orbital-Setup-0.6.1.exe from Releases (latest Windows build)
2. Run the installer and follow the prompts
3. Launch Orbital from the Start Menu or desktop shortcut

macOS

1. Download Orbital-0.6.2-macOS.dmg from Releases
2. Open the DMG and drag Orbital to your Applications folder
3. Launch Orbital from Applications or Spotlight

Requires macOS 13 (Ventura) or later, Apple Silicon (M1 or newer). Intel Macs are not supported by this build (the bundle is arm64-only).

From Source

# Clone the repository
git clone https://github.com/zqiren/Orbital.git && cd Orbital

# Install Python dependencies (Python 3.11+)
pip install -e ".[desktop]"

# Install frontend dependencies (Node.js 18+)
cd web && npm install && cd ..

# Start the daemon
python -m uvicorn agent_os.api.app:create_app --factory --port 8000

# Start the frontend dev server (separate terminal)
cd web && npx vite --host 127.0.0.1 --port 5173

Open http://localhost:5173 in your browser. The setup wizard runs on first launch.

Note on Sleep/Shutdown

Orbital prevents system sleep while agents are actively working (via OS-level sleep inhibition on Windows and macOS). When all agents are idle, sleep is re-allowed. The system tray icon shows current agent activity status.

Development

Backend

# Start daemon
python -m uvicorn agent_os.api.app:create_app --factory --port 8000

# Restart with fresh code
bash scripts/restart-daemon.sh

Frontend

cd web
npm install
npx vite --host 127.0.0.1 --port 5173

Key Paths

Testing

# Unit + platform tests
python -m pytest tests/unit/ tests/platform/ -q \
  --ignore=tests/platform/test_consumer3_wiring.py

# TypeScript check (zero errors expected)
cd web && npx tsc -b

# Daemon integration test
bash scripts/restart-daemon.sh
curl http://localhost:8000/api/v2/projects

Known pre-existing test notes:

• test_consumer3_wiring.py — requires Windows sandbox user configuration
• test_e2e.py, test_user_stories.py — require a real LLM API key set via AGENT_OS_TEST_API_KEY

Roadmap

Shipped

• Multi-provider LLM routing with fallback rotation
• Three autonomy presets with cascade to sub-agents
• Streaming chat with real-time WebSocket events
• Browser automation with anti-detection (Patchright)
• Continuous operation via schedule and file-watch triggers
• Natural language trigger creation
• Cloud relay with push notifications and device pairing
• Context compaction with pre-compaction memory flush
• Prefix-cache-optimized prompt assembly (v0.4.2)
• Per-project budget limits and cost tracking
• Credential management (API keys + website credentials)
• Desktop app with system tray and native window
• Agent loop safety guards (iteration cap, repetition, ping-pong, circuit breaker)
• OS-level sleep prevention during agent activity
• Sub-agent delegation with @mention routing

Next

• Webhook triggers — HTTP endpoint that fires agent tasks on incoming webhooks
• Pipeline triggers — Chain project outputs as inputs to other projects
• Network isolation — Per-project domain allowlists enforced at OS level
• Linux sandboxing — bubblewrap enforcement
• Code signing — Eliminate SmartScreen warnings on Windows
• Auto-resume on daemon restart — Restore in-progress sessions

Why I built this

I loved Claude Projects. I hated that I couldn't let an agent update the project, and that it didn't live on my machine.

I loved OpenClaw. I hated the lack of control — no budget, no sandbox, no way to supervise from my phone when I stepped away.

Orbital is the thing I wanted. One agent that remembers everything we've done. Sandbox, budget, approvals I control. The phone to check in when I'm not at my desk. Claude Code, Codex, Gemini CLI as the hands it delegates to — swap the hands, keep the memory. An agent that never starts from zero.

Built nights and weekends while working full-time. Still very early. Feedback and issues welcome.

License

Orbital is licensed under the GNU General Public License v3.0.

Orbital — The agent that never starts from zero.
Copyright (C) 2026 Orbital Contributors

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.