Orbital AI Agent

by zqiren• 970•• Scanned•Claim this listing•Request removal

Developer Toolsagentagent frameworkagent managementagent memoryagent orchestration

Context is yours. Agents are replaceable.

Orbital is an open-source ai agent by zqiren, written mainly in Python, with 970 GitHub stars and the GPL-3.0 license. Its code was last updated Oct 30, 2026.

about README security reviews

English · <a href="README.zh-CN.md">简体中文</a> Codex hits its usage limit mid-task. Claude Code picks up in the same conversation. <img src="docs/screenshots/hero-agent-switch.gif" alt="In one Orbital conversation Codex stops with a usage-limit error; the user opens the agent picker, which shows Codex's limit reached and Claude Code with 91% left, switches to Claude Code, and it reads the project's context files and answers the original question" width="100%"> Codex stops at its usage limit. One switch in the picker, and Claude Code continues the answer from the project's context. <img src="docs/screenshots/orbital-logo.png" alt="Orbital" width="80"> <h1 align="center">Orbital</h1> The project agent <h3 align="center">Every agent owns a session. Orbital owns the project.</h3> Orbital is the context steward for your agents. It maintains your project's context so every agent works from the same one. Whatever any agent produces or learns, Orbital keeps for all the others to reuse. Your agents evolve together on the same project. Context is yours. Agents are interchangeable. <a href="https://github.com/zqiren/Orbital/releases/latest/download/Orbital-Setup.exe"><img src="https://img.shields.io/badge/Windows-Download_.exe-0078D6?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTMgNC42bDcuNi0xLjA1djcuMzVIM3ptOC41LTEuMkwyMSAyLjF2OC44aC05LjV6TTMgMTIuMWg3LjZ2Ny4zNUwzIDE4LjR6bTguNSAwSDIxdjguOGwtOS41LTEuM3oiLz48L3N2Zz4=" alt="Download the Windows installer (.exe)"></a>    <a href="https://github.com/zqiren/Orbital/releases/latest/download/Orbital-macOS.dmg"><img src="https://img.shields.io/badge/macOS-Download_.dmg-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download the macOS installer (.dmg)"></a> Set up in under 5 minutes. No Python or Node required. Bring your own API key. New here? Read the <a href="https://orbital.top/en/guide/">user guide</a>. One-minute demo: one task, two agents, nothing re-explained

https://github.com/user-attachments/assets/5f1373bc-2c3e-440b-af52-77ecbd80c27f

Why a project agent?

Is your context actually yours?

You're three rounds into a design discussion with Claude Code when it stops with "You're out of usage credits." Your Codex quota is sitting right there, but Codex knows nothing about this project: the goal, the two decisions you just made, the half-edited files. You'd have to explain all of it again.

<img src="docs/screenshots/in-session-agent-switch.png" alt="The agent picker in an Orbital chat: each agent shows how much of its usage window is left (Claude Code 67% of its week, Codex 84%), and switching to another agent continues the same conversation" width="100%"> Every agent's remaining quota sits in the picker. Pick another one and it continues from the same project context.

It isn't only usage limits. People already use several capable agents at work: for the newest model, the leftover quota, or because a particular tool is better at the job. But the plan you settled with Claude Code, the file Codex left half-edited, the trade-off you decided in Cursor: each one is locked inside its own session. Close the session or switch tools, and that context is out of reach.

So you carry the project between them: restating goals, explaining previous decisions, locating artifacts, and checking what was left unfinished.

You are the agent's intern: copying and pasting, ferrying context, remembering where all the odd files live, while the agent gets the thinking.

Orbital takes the context out of the session and puts it back in your local folder, and changes the unit of work from the session to the project.

The project agent records every agent's progress on the project, so the next agent picks up the task with the full context. Whatever one agent produces or learns is kept for every other agent to draw on and reuse. No wheel gets reinvented: all your agents evolve together on the same project.

Individual agents complete tasks. Orbital moves the whole project forward.

What it means to own the project

Orbital maintains five things that normally disappear or fragment between agent sessions — all of them as plain files in your project folder:

State — what is true about the project now (PROJECT_STATE.md)
Decisions — what was decided and why (DECISIONS.md)
Lessons — what the project has learned (LESSONS.md)
Work — what is running, completed, or blocked (queue.json). Every queued task ends Completed or Blocked — an agent that stops without a verdict gets re-prompted, then force-blocked with a reason. Nothing drifts away silently.
Artifacts — what the agents researched, wrote, or built (the workspace itself, plus orbital/output/)

These stay in the local project and become context for future work. On a cold start, Orbital assembles them into its own system prompt before it acts.

When Orbital delegates, the worker is pointed at those same files and told they are authoritative — that briefing is rendered fresh on every dispatch, not something you paste in. Each worker also keeps its own memory file inside the project, so it accumulates its own experience across dispatches. When the task finishes, Orbital reads the result and records what matters back into the project.

The worker can change. The project continues.

<a href="https://discord.gg/57v7dku8JU"><img src="https://img.shields.io/badge/Discord-Join_the_community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join the Orbital Discord"></a> <img src="docs/screenshots/wechat-qr.png" alt="WeChat QR code: add the author and get pulled into the Orbital user group" width="150"> WeChat: scan to add me, I'll pull you into the user group

Quick Start

<details> <summary>Expand the 4-step walkthrough (with screenshots)</summary>

Want the step-by-step version with screenshots? See the Orbital user guide: API keys, projects, switching agents, the task queue, automations and project settings.

Launch Orbital — the setup wizard walks you through four steps: first confirm the coding agents Orbital found on this computer, then import the projects you already worked on with them (both can be skipped), then set the API key and connect your accounts.

Step 3 — LLM Provider: In mainland China, tap Sign in with TokenDance, authorize, and start on free tokens. Otherwise pick a provider from the preset cards, follow the key-console link to grab an API key, and paste it in. Supports DeepSeek, Anthropic, OpenAI, Moonshot, and a dozen other providers.
<img src="docs/screenshots/apikey-setup.png" alt="Setup wizard step 3: pick an LLM provider and enter your API key" width="480">
Step 4 — Connect Your Accounts: Link API connectors (Google Calendar, Drive) and sign in to sites your agents will need (Google, GitHub, etc.) so they can browse without getting blocked by CAPTCHAs. Everything here is optional and can be done later in Settings.
<img src="docs/screenshots/connect-accounts.png" alt="Setup wizard step 4: connect accounts — API connectors and agent browser sign-in" width="480">
Create a project — give it a name, pick a workspace directory, set an autonomy level

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

</details>

See the project stay under one manager

<img src="docs/screenshots/memory-context.png" alt="The orbital/ memory files (PROJECT_STATE.md, DECISIONS.md, LESSONS.md, INDEX.md, ASKS.md), maintained by the agent and read back every session" width="100%"> The project agent keeps the project's state, decisions, and lessons current across sessions. <img src="docs/screenshots/delegation-claudecode.png" alt="The project agent files a bug and dispatches Claude Code, which investigates for nine minutes against the same project context and reports the root cause and a spec back into the workspace" width="100%"> It delegates to Claude Code, Codex, or Gemini CLI against the same project context, then records the result.

How Orbital compares

Memory, scheduling, and sub-agents are table stakes now — every tool below has them. These are the three questions where the answers still differ.

July 2026	Orbital	Claude Code	Codex	Hermes	OpenClaw
Can a different agent pick up the next task?	✅ Claude Code, Codex, Gemini CLI, Cursor, any CLI	❌ Claude workers	❌ Codex workers	❌ Hermes workers	Partial (external harnesses via ACP)
What stops a queued task from drifting?	✅ Enforced Completed/Blocked closure	❌	❌	❌	❌
Who owns the budget, approvals, and audit trail?	✅ The project	Partial (permissions + run history)	Partial (approvals + enterprise audit)	Partial (command approvals)	Partial (approvals + logs)

The short version: the difference isn't any one capability — it's that the project, not the session, is the unit that owns state, workers, and governance.

Feature Deep Dives

<details> <summary>Orbital Is / Is Not</summary>

Orbital IS	Orbital IS NOT
A project workspace where you and your agents share the same files, history, and context	A cloud service — everything runs on your machine
A sub-agent coordinator: Claude Code via SDK, Codex via app-server, and Gemini CLI, Cursor, or other workers via PTY/ACP	An OpenClaw fork — custom agent loop, built from scratch
Remote supervision: approve actions, browse workspace files, upload from phone	A chat wrapper — agents run continuously via cron and file watchers
Budget controls, autonomy presets, credential management (OS keychain)	Fully autonomous God Mode (yet) — scheduler-driven today, full autonomy on the roadmap

</details>

How the project stays under one manager

<details> <summary>Project & Workspace Model</summary>

Each project maps to a workspace directory and maintains its own sessions, queue, triggers, and configuration.

<img src="docs/screenshots/files.png" alt="The workspace file tree with the agent's accumulating output and the orbital/ memory files" width="100%"> Browse, preview, and upload files in each project's workspace — and watch the agent's output accumulate

{workspace}/
+-- AGENTS.md                           # Onboarding signpost for external agents (seeded at creation, user-owned)
+-- 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 + per-worker MEMORY.md
    +-- tool-results/                   # Tool output artifacts
    +-- output/                         # Agent work artifacts
    |   +-- screenshots/                # Browser screenshots
    |   +-- pdfs/                       # Saved PDFs
    |   +-- shell-output/               # Shell command output
    +-- queue.json                      # Task queue (queued / running / completed / blocked)
    +-- PROJECT_STATE.md                # Current-state scratchpad (overwrite)
    +-- DECISIONS.md                    # Durable decisions + reasoning
    +-- LESSONS.md                      # Durable heuristics / playbooks
    +-- INDEX.md                        # Navigation map: file tree + one line per file
    +-- DECISIONS_ARCHIVE.md            # Demoted decisions (read-on-demand)
    +-- LESSONS_ARCHIVE.md              # Demoted lessons (read-on-demand)

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

Session format: One JSON line per message (role, source, content, timestamp, tool_calls). Append-only with file locks. Never modified except during compaction.

</details> <details> <summary>Context Management & Compaction</summary>

This is how the project agent keeps context available across sessions. The agent-maintained Layer-1 files are injected every turn (bounded per file) and consolidated at session boundaries:

File	Purpose	Bound
`PROJECT_STATE.md`	Current-state scratchpad — what's true now (overwrite, not a changelog)	token cap → trim oldest
`DECISIONS.md`	Durable decisions + reasoning (merge-and-supersede, never contradict)	token cap → demote oldest-cold to archive
`LESSONS.md`	Durable heuristics / technical playbooks (kept intact, never word-trimmed)	token cap → demote oldest-cold to archive
`INDEX.md`	Navigation map only: file tree + one sentence per file	one-sentence format + token cap
`DECISIONS_ARCHIVE.md`, `LESSONS_ARCHIVE.md`	Demoted durable entries, read-on-demand (pointed to by INDEX)	unbounded

Each entry carries system-managed metadata (id / created / touched / tag) so dedup runs on recency. Per-turn injection bounds each file to a budget derived from the active model's context window. Session-end runs a deterministic size backstop (demote/trim, never an LLM call) plus a best-effort LLM dedup/merge that fixes contradictions. (SESSION_LOG.md was retired; the Layer-1 files are injected every turn, so a separate session history is redundant.)

Cold resume: On session start, these files are assembled into the system prompt so the agent can reorient before it acts.

<img src="docs/screenshots/memory-decisions.png" alt="DECISIONS.md — the agent's decision log with rationale, maintained across sessions" width="100%"> <img src="docs/screenshots/memory-lessons.png" alt="LESSONS.md — patterns and pitfalls the agent learned, read back before each task" width="100%"> DECISIONS.md and LESSONS.md — written by the agent as it works, and carried into every future session

Compaction (when context usage exceeds 80%): a memory record turn (the agent decides what to keep in the project memory files), LLM-driven summarization of older messages, recent messages kept intact, post-compaction reorientation with project goals and current state.

Prefix caching (v0.4.2): the system prompt is split into static, semi-stable, and truly-dynamic sections so up to ~95% of input tokens hit the provider's prefix cache on follow-up turns. See the v0.4.2 release notes for benchmark numbers.

</details> <details> <summary>Sub-Agent Delegation</summary>

Orbital is not tied to a single AI tool. The project agent plans and delegates, while specialized workers execute — each reading the same accumulated project context. Any CLI-based agent can be registered via a manifest file; Claude Code, Codex, Cursor, Gemini CLI, Aider, Cline, Goose, Copilot CLI, and Continue ship with one.

Each dispatch renders a fresh inheritance prompt that points the worker at PROJECT_STATE.md, DECISIONS.md, LESSONS.md, INDEX.md, the project's instructions, and its skills — declaring them authoritative and off-limits for writes. Workers read them on demand rather than receiving a pasted copy, so the brief never goes stale.

<img src="docs/screenshots/subagent-memories.png" alt="Sub-Agent Memories panel — each sub-agent keeps its own long-term memory, curated per project, that it reads on every dispatch" width="100%"> Each sub-agent keeps its own long-term memory across dispatches — curate what it remembers... <img src="docs/screenshots/delegation-claudecode.png" alt="The project agent dispatches a bug investigation to the Claude Code sub-agent, which runs 50 tool calls and reports the root cause and spec back into the workspace" width="100%"> ...then delegates a task to Claude Code, reviews the result, and writes it back into the project

Transport types:

Transport	Use Case
Codex app-server	Native Codex JSON-RPC over stdio, with structured lifecycle and approvals
Pipe	stdin/stdout subprocess, JSON streaming
PTY	Pseudo-terminal for interactive agents — Gemini CLI, Aider, Cline, Goose, Copilot CLI, Continue
SDK	Direct Claude SDK integration
ACP	Agent Communication Protocol — Cursor, via its official ACP server

Note: Codex uses its native app-server path, not PTY or ACP. Orbital launches codex app-server and speaks JSON-RPC directly. ACP is available for any ACP-compliant worker; PTY is the default for other interactive CLI agents.

</details> <details> <summary>Task Queue</summary>

Each project has a queue, stored with the project at orbital/queue.json. Add tasks — pin urgent ones to the front — and your agent works through them one at a time, in order, without you watching.

The agent must declare an outcome on every item; it can't silently drift to the next one:

Outcome	What happens
Completed	The agent reports a short summary; the item moves to Completed and the queue advances.
Blocked	The agent states the reason (missing credentials, ambiguous requirements, …); the item moves to Needs Attention and the queue moves on. You unblock it when ready.

Pause to steer. Pause the queue mid-item to chat freely — your clarifications land in the same session, so the agent sees them when you resume.

Continuity by design. Each completed item's artifacts are already in the project when the next item starts, so the agent can use them when supervising later tasks. The project's triggers (schedules and file watchers) are listed in the queue's Automations section alongside your tasks.

<img src="docs/screenshots/queue-paused.png" alt="A paused queue: Now Running empty, one blocked item under Needs Attention with the agent's reason, two queued tasks, and completed items with their summaries" width="100%"> Queue tasks and walk away — each finished one becomes context the next builds on </details> <details> <summary>Workbench — one place to send any task (beta)</summary>

The Workbench is the home screen: one box for everything you want done, across every project. Type the task in a line and Orbital routes it to the right project and the right agent, with that project's context. Or pick the project and the agent yourself from the two chips under the box.

Under the box is one list of cards, newest first: tasks that are running, replies waiting for you to read, and questions an agent can't settle without you, each marked with the project it came from. A question shows the choices the agent offered, so one tap answers it. Its detail renders as markdown, and the reply field takes typed words or attached files. Tap a card's title to open its session, or the check mark once you've dealt with it.

<img src="docs/screenshots/workbench.png" alt="Workbench: a box to send any task, with project and agent chips, above one list of cards: a running task, finished replies from Codex and Claude Code, and a question with one-tap options, each labelled with its project and the agent that took it" width="100%"> One place to send a task, and to see every status, reply and question across your projects </details> <details> <summary>Quick Tasks</summary>

The sidebar includes a Quick Task section for fire-and-forget interactions. Scratch projects skip the full project creation flow — useful for one-off tasks that don't need a dedicated workspace.

<img src="docs/screenshots/quick-task.png" alt="A fire-and-forget Quick Task (browsing Hacker News) returning structured results" width="100%"> </details> <details> <summary>Self-Improving Skills</summary>

Agents create reusable skills from multi-step workflows and consult matching skills before starting similar tasks. Skills are stored as SKILL.md files in the workspace and managed through the Settings UI — another way the project gets more capable the longer it runs.

<img src="docs/screenshots/skills.png" alt="Skills section in project settings: reusable operational patterns the agent follows" width="100%"> Skills like Efficient Execution, Learning Capture, and Task Planning shape how your agent works — and the agent adds its own </details>

Tools & execution

<details> <summary>Built-in Tool Suite</summary>

The project agent has access to these tool categories:

Category	Tools	Description
Shell	`shell`	Command execution with network-aware detection
File	`read`, `write`, `edit`, `glob`, `grep`	File operations and search within workspace
Browser	26 actions via Patchright	Navigate, click, type, extract, screenshot, multi-tab, PDF, web search, URL fetch
Triggers	`create_trigger`, `list_triggers`, `update_trigger`, `delete_trigger`	Schedule and file-watch triggers via natural language
Credentials	`request_credential`	Agent-initiated credential request — opens secure modal
Delegation	`agent_message`	Route tasks to sub-agents
Access	`request_access`	Request sandbox portal to a path outside the workspace

</details> <details> <summary>Browser Automation</summary>

Built on Patchright (a Playwright fork with anti-bot-detection):

Stealth mode: Anti-automation detection scripts injected into every browser context
Shared profile: One browser profile across all projects — log into services once, all agents share cookies
Accessibility-first: snapshot returns an accessibility tree with [ref=eN] element references for reliable interaction
26 browser actions: navigate, click, type, fill, press, hover, select, drag, upload, snapshot, screenshot, extract, search (page), evaluate, tab management, go back/forward, reload, wait, PDF export, web search, URL fetch, batch

<img src="docs/screenshots/5A-mobile-browsing-activity.png" alt="Mobile view of the agent browsing Hacker News, each browser step and its reasoning visible in the chat" width="300"> Your agent browsing Hacker News, with every step visible from your phone </details> <details> <summary>Continuous Operation & Triggers</summary>

Agents run continuously via triggers — no manual intervention needed. Create triggers through natural language in the chat:

"Watch the uploads/ folder for new .jpg files and analyze them" "Run a research scan every morning at 6 AM"

The project agent translates this into a create_trigger tool call with the appropriate type and parameters.

Trigger types:

Type	Configuration	Example
Schedule	Cron expression + timezone	`0 6 * * *` (daily at 6 AM)
File Watch	Path + glob patterns + debounce	`uploads/*.jpg`, 5s debounce

<img src="docs/screenshots/file-watch-trigger.png" alt="File watch trigger editor: watching evidence/inbox/ for new bug screenshots, with its folder, file patterns, debounce, who runs it, and the prompt" width="100%"> File watch trigger: watches evidence/inbox/ for new bug screenshots and triages each one on arrival <img src="docs/screenshots/scheduled-trigger.png" alt="Schedule trigger editor: a weekly backlog triage every Monday at 10 AM, with its cadence, time zone, who runs it, and the prompt" width="100%"> Schedule trigger: a weekly backlog triage every Monday at 10 AM

Real-world example: a bug-report inbox with file watch

<img src="docs/screenshots/4B-mobile-watch-1.png" alt="Mobile chat: asking the agent to watch evidence/bug-reports/, and the agent creating the file-watch trigger" width="280">   <img src="docs/screenshots/4B-mobile-watch-2.png" alt="Mobile chat: the triggered run reading a dropped bug report, filing it in the backlog, and having Claude Code write the spec" width="280"> Left: "Watch evidence/bug-reports/ for new bug reports." Right: drop a report in, and the agent files it and gets a spec written. </details> <details> <summary>LLM Provider Routing & BYOK</summary>

14 providers supported out of the box:

Anthropic, OpenAI, DeepSeek, Moonshot (Kimi), Groq, Google Gemini, xAI, Mistral, Together, OpenRouter, Zhipu, Qwen, TokenDance (词元跳动 — China-mainland model router), plus a custom entry for any OpenAI-compatible endpoint (e.g., Ollama, Azure OpenAI, self-hosted models).

SDK routing: Anthropic SDK for Anthropic, OpenAI SDK for OpenAI-compatible providers
Per-model metadata: Display name, tier, context window, max output, capabilities (vision, tool use, streaming), pricing
Fallback rotation: When the primary provider fails, the loop rotates to fallback providers with error classification (transient, rate limit, abort)

</details>

Control & safety

<details> <summary>Autonomy & Approval System</summary>

Three autonomy presets control how much supervision agents receive:

Preset	Shell	File Write	Browser	Description
Hands-off	Auto	Auto	Auto	Maximum autonomy. Only `request_access` requires approval.
Check-in	Approval	Approval	Write only	Balanced. Default for external agents.
Supervised	Approval	Approval	All except read	Maximum oversight.

<img src="docs/screenshots/settings-autonomy-budget.png" alt="Project settings: autonomy presets (Hands-off / Check-in / Supervised) and per-project budget controls" width="100%"> Pick an autonomy level and set budget limits per project

Approval flow:

Interceptor catches tool call based on autonomy rules
Frontend shows an Approval Card with tool name, arguments, and context
User can Approve, Deny, or Auto-approve for 10 minutes
Per-action bypass: same tool+args auto-approved for 60 seconds

<img src="docs/screenshots/5B2-mobile-approval-card.png" alt="Mobile approval card: approving an agent action from the phone with full context" width="300"> Approve agent actions from your phone — with full context and optional guidance </details> <details> <summary>Cost Controls & Budget Limits</summary>

Per-project budget limits prevent runaway spending:

Setting	Description
`Budget Limit (USD)`	Maximum spend for the project
`Budget Action`	`ask` (pause and prompt user) or `stop` (halt the agent)
`Spent`	Running total with reset option

The agent loop tracks cumulative token usage and computes cost using per-model pricing from the provider registry. When the budget threshold is reached, the configured action fires (ask pauses the session; stop halts the agent). Budget events do not currently trigger push notifications.

<img src="docs/screenshots/settings-budget.png" alt="Budget settings: spend limit, reset period, pause-or-stop action, a live per-model cost breakdown, and an editable pricing table" width="100%"> Set a limit and a reset period; watch the live per-model spend and cost breakdown </details> <details> <summary>Mobile Remote Control</summary>

Control agents from your phone on the local network or via a cloud relay.

<img src="docs/screenshots/4A-mobile-dashboard.png" alt="Mobile dashboard: all projects at a glance" width="280">   <img src="docs/screenshots/5C-mobile-approved.png" alt="The agent completing its work after a mobile approval" width="280"> Left: Project dashboard on phone. Right: Your agent completes its research after you approve from anywhere.

Local network: Scan the QR code in Settings to open Orbital on your phone via LAN.

<img src="docs/screenshots/qr-code-lan-pairng.png" alt="QR code in Settings for mobile access on the local network" width="100%"> Scan to open Orbital on your phone — same Wi-Fi network required

Cloud relay (optional): Deploy a relay server for access outside your home network. Push notifications for approval requests and agent status changes.

</details> <details> <summary>Credential Management</summary> <img src="docs/screenshots/credential-store.png" alt="Credential store: website passwords stored in the system keychain, with browser sign-in and connectors" width="100%"> Website credentials stored in your system keychain. Your agent always asks permission before using them.

API keys: Stored in OS keychain (keyring), masked in API responses, per-project BYOK override
Website credentials: Metadata in credential-meta.json, values in OS keychain. The request_credential tool lets agents request credentials mid-session via a secure modal — credentials never appear in chat history.

</details> <details> <summary>Loop Safety Guards</summary>

The agent loop includes multiple safety mechanisms to prevent runaway execution:

Guard	Threshold	Behavior
Token budget	100M tokens (configurable)	Hard stop on cumulative usage
Repetition detection	5 identical action hashes	Forces different approach
Ping-pong detection	3 identical consecutive pairs	Breaks alternating cycles
Circuit breaker	2 consecutive identical errors	Blocks tool until new user message
Context overflow	3 consecutive overflows	Hard stop after progressive reduction

</details> <details> <summary>Desktop App & System Tray</summary>

Orbital ships as a desktop application bundled with PyInstaller:

System tray: Agent activity status, quick access menu, running port in tooltip
Native window: Embeds the React frontend via pywebview — no browser needed
Daemon lifecycle: Desktop app spawns the daemon on launch, manages port allocation, cleans up on exit
Sleep prevention: Blocks system sleep while agents are active (Windows SetThreadExecutionState), re-allows when idle

</details>

Architecture

Orbital is one persistent agent bound to a project — not a chat session. It acts as a local control plane for the project's workspace, instructions, state, queue, budget, and approval rules. It plans, delegates, supervises, and records outcomes; worker agents execute against the same project context. 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["Worker Transports<br/>Codex app-server · SDK · PTY · ACP · Pipe"]
        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:

The agent owns the project: it maintains structured state, decisions, lessons, and session history so planning and accountability remain in one place
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.

Installation

Windows

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

<details> <summary>Windows SmartScreen Warning</summary>

Orbital is not yet code-signed, so Windows will show a security warning:

Windows protected your PC — Microsoft Defender SmartScreen prevented an unrecognized app from starting.

Click "More info" then "Run anyway". Code signing will be added in a future release.

</details> <details> <summary>The AgentOS-Worker account</summary>

Orbital runs agent commands as a separate, low-privilege local Windows account named AgentOS-Worker, so an agent cannot read your user profile, your browser data or your credentials. The installer says so before it writes a single file.

The account is created during installation and does not appear on the sign-in screen.
Its password is random; nobody knows it, and nobody needs to.
Uninstalling Orbital removes the account.
Giving that account read access to your developer tools (the folders holding npm, cargo, Python and so on) happens in the background the first time Orbital starts; it does not slow the installation down.
Inside a project folder the account cannot write .git\config or .git\hooks (those run code outside the sandbox), so git remote add, git config --local and hook edits fail for the agent; every other git command — git status, git log, git add, git commit, git checkout — works.

The AgentOS-Worker you see under Computer Management > Local Users and Groups > Users carries a description saying it belongs to Orbital.

</details>

macOS

Download the Orbital-*-macOS.dmg from Releases
Open the DMG and drag Orbital to your Applications folder
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).

Release builds are Developer-ID signed and notarized by Apple, so the app opens normally on first launch — no Gatekeeper warning or "Open Anyway" workaround needed. (If you built Orbital from source or grabbed a CI branch artifact, that build is ad-hoc signed and macOS will still ask you to approve it once via right-click → Open.)

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

Component	Path
FastAPI app factory	`agent_os/api/app.py`
Agent loop	`agent_os/agent/loop.py`
Tool implementations	`agent_os/agent/tools/`
Autonomy interceptor	`agent_os/daemon_v2/autonomy.py`
LLM providers	`agent_os/agent/providers/`
Trigger manager	`agent_os/daemon_v2/trigger_manager.py`
Browser manager	`agent_os/daemon_v2/browser_manager.py`
Sub-agent manifests	`agent_os/agents/manifests/`
Desktop entry point	`agent_os/desktop/main.py`
System tray	`agent_os/desktop/tray.py`
Frontend components	`web/src/components/`

Testing

# Unit + platform tests
python -m pytest tests/unit/ tests/platform/ -q

# 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_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 a pre-compaction memory record turn
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

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 accountable for the whole project: the plan, the decisions, the queue, the budget, and the approvals. The phone to check in when I'm not at my desk. Claude Code, Codex, and Gemini CLI as workers it can choose for the job without handing away the project's context.

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

Star History

Telemetry

Orbital sends one anonymous aggregate per day — counters, enums, and booleans only. Never prompts, files, paths, model output, or any project/session identifier. The exact outbound JSON is inspectable verbatim in Settings → Data & privacy, where a single toggle turns it off. The full published schema is in docs/TELEMETRY.md.

License

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

Orbital — Every agent owns a session. Orbital owns the project.
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.

Orbital alternatives

View more →

Similar ai agents in Developer Tools, ranked by GitHub stars. Compare licence, recent activity and scan status before you choose.

Name	Stars	Licence	Last updated	Scan
Orbital (this page) zqiren	970	GPL-3.0	Oct 30, 2026	Scanned, no flagged issues
Deepseek Harness deepseek-ai	268k	MIT	Oct 30, 2026	Scanned, no flagged issues
Ponytail DietrichGebert	182k	MIT	Oct 29, 2026	Scanned, no flagged issues
Orca stablyai	112k	MIT	Nov 1, 2026	Scanned, no flagged issues
Deer Flow bytedance	85k	MIT	Nov 1, 2026	Scanned, no flagged issues
Ruflo ruvnet	80k	MIT	Nov 1, 2026	Scanned, no flagged issues

Orbital AI Agent

Why a project agent?

What it means to own the project

Quick Start

See the project stay under one manager

How Orbital compares

Feature Deep Dives

How the project stays under one manager

Tools & execution

Control & safety

Architecture

Installation

Windows

macOS

From Source

Note on Sleep/Shutdown

Development

Backend

Frontend

Key Paths

Testing

Roadmap

Shipped

Next

Why I built this

Sponsors

Star History

Telemetry

License

Orbital alternatives