Orbital

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

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.

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:

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.

DECISIONS.md and LESSONS.md — written by the agent as it works, and carried into every future session

Compaction (when context usage exceeds 80%): memory flush, 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.

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.

Each sub-agent keeps its own long-term memory across dispatches — curate what it remembers...

...then delegates a task to Claude Code, reviews the result, and writes it back into the project

Transport types:

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.

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:

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.

Queue tasks and walk away — each finished one becomes context the next builds on

Some things an agent genuinely cannot finish for you: a spend decision, a message that has to come from your account, a judgment call between three options it already researched. As the agent works, it flags those in the project's state file — and the Workbench collects them from every project into one list.

Each card carries its provenance, so you are never asked to act on a bare instruction. Expand Why I believe this and you see the evidence the agent recorded and the session it came from. Cards sort overdue-first, then oldest, and each one exits in a single tap — Done once you've handled it, Delete when it stopped mattering. Tapping the card itself opens that project's chat with the decision pre-filled, so answering is one message instead of a hunt for context.

The Today strip along the top lists the day's automation slots, including the ones that already fired — so a single glance covers both what needs you and what ran without you.

Every project's open decisions in one list — with the evidence behind each one a click away

Automations you set up months ago shouldn't fire invisibly. Every enabled schedule trigger projects its upcoming runs onto a week grid, so the rhythm of the project is something you can see rather than remember. Dated commitments the agent recorded in the project state land on the same grid and drop off once they're resolved, and connecting Google Calendar brings those events into the same view.

The project agent can read this calendar too, so "what's already on the schedule" is context it plans around instead of something you have to restate.

The week ahead, as your automations will actually run it

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.

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.

Skills like Efficient Execution, Learning Capture, and Task Planning shape how your agent works — and the agent adds its own

The project agent has access to these tool categories:

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

Your agent browsing Hacker News, with every step visible from your phone

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:

File watch trigger: watches evidence/inbox/ for new bug screenshots and triages each one on arrival

Schedule trigger: a weekly backlog triage every Monday at 10 AM

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

Left: "Watch evidence/bug-reports/ for new bug reports." Right: drop a report in, and the agent files it and gets a spec written.

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)

Three autonomy presets control how much supervision agents receive:

Pick an autonomy level and set budget limits per project

Approval flow:

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

Approve agent actions from your phone — with full context and optional guidance

Per-project budget limits prevent runaway spending:

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.

Set a limit and a reset period; watch the live per-model spend and cost breakdown

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

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.

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.

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.

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

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

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.

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.

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