Concepts

Orbit has five layers. Each answers one question: when work runs, what the work is, how it runs, who runs it, and what bounds it. Each page below covers one layer: what it guarantees and what it refuses. For commands, see the how-to guides.

When Routines and auto-tasks Fire jobs on a schedule; file recurring chores as tasks. What Tasks The durable, reviewable unit of work. How Activities and jobs Reusable execution units and the jobs that chain them. Who Agents Provider CLIs and the crews tasks run under. Bounds Policies Filesystem rules that bound every run.

Pages

Tasks

Lifecycle, statuses, the two approval gates, transition rules, and task artifacts.

Activities and jobs

Reusable execution units, the jobs that chain them, and how a task's required tools reach a run.

Routines and auto-tasks

The host scheduler clock, routines that fire jobs, auto-tasks that file chores, and the limits on unattended work.

Policies

Filesystem profiles and the deny rules that bound what a run can read and write.

Agents

Provider CLIs, executors, tool policy, and crews: the named provider and model a task runs under.

Capabilities

Plan and govern

• Durable tasks with intent. Tasks carry acceptance criteria, a file scope, dependencies, and typed relations. They move through proposed → backlog → in-progress → review → done, and that state survives sessions and branches.
• Structured audit log. Every tool call, provider exchange, and state transition is recorded as an append-only, queryable event tagged with the agent and model that produced it (orbit audit).
• Friction ledger. When the work was harder than it should have been, whether from a confusing error, a missing flag, or an undocumented convention, the agent records it with orbit friction add instead of quietly working around it. A task that resolves the friction closes it on completion.
• Local search. orbit search runs fast lexical search (SQLite FTS5) over tasks and frictions. It needs no model download.

Execute safely in parallel

• Isolated, sandboxed runs. Each run gets its own git worktree and runs its agent CLI under sandbox-exec on macOS or Bubblewrap on Linux. On Linux, workers use memory-bounded cgroups when a systemd user manager is available; see worker containment.
• Conflict-aware scheduling. Runs reserve their task’s files as locks before starting, so overlapping work waits in line instead of producing merge conflicts later. Interactive work can hold an advisory or hard path lease with orbit lease instead; see Path leases.
• Gated pipeline. Each run goes plan → execute → review, with repair budgets and failure recovery. Dependencies gate admission, so you declare the order once and the queue enforces it.
• Seven agent CLIs, routed by crews. Claude Code, Codex, Copilot, Grok, Gemini, Antigravity, and Muse Code (the Cursor, Pi, and OpenCode lanes were retired). Crews pin a provider, model, and supported effort level. Complexity-tiered, weighted crew pools spread the work across them (how routing works).
• Read-only exploration and operator steering. Opt-in exploration lets implementing and review-repair agents ask an explorer crew bounded code-reading questions. Opt-in mid-run steering delivers new operator comments and holds promotion until the run consumes them (agent execution).

Run unattended

• Bounded drains. orbit run auto --for 4h --concurrency 8 ships the backlog until the time window closes. orbit run readiness previews what would run without starting anything. Or ask your agent to run one: the orbit-orchestrate skill prepares the backlog, starts the drain, and works through failed runs.
• Scheduled task starts. A task’s optional not_before holds it until its earliest start time. The hold lifts on the next admission pass; approval and the other admission checks still apply. See Scheduled tasks.
• Opt-in completion. --complete merges PRs once GitHub allows it and closes tasks after the merge is verified. For distributed handoffs, the owner can instead authorize completion with workflow.distributed_completion = "done"; see delivery workflows.
• Continuous review. The shipped code-review, qa-sweep, and security-review auto-tasks read everything that landed since their last run, verify findings against live code, and file confirmed ones as tasks with file:line evidence.
• Recurring work as data. Scheduled task templates live in .orbit/auto_tasks/*.yaml, and one machine scheduler (orbit clock) runs routines and auto-tasks.
• Multi-machine. A distributed drain spreads a backlog across machines through durable claims. A federated MCP server puts local and SSH-remote workspaces under one namespace.

Observe and extend

• Dashboard (orbit web serve). Shows the task backlog, live audit feed, managed-execution cost, jobs, frictions, and effective config, with inline editing. The Tasks drain card and Analytics › Forecast estimate time, cost and tokens to drain the backlog. Agent scorecards link each role’s scores to their evidence; host resource analytics compare measured CPU and memory with admission forecasts.
• Experiments. Operators run randomized experiments over agent treatments with orbit experiment: sticky assignment, overlays, and a per-arm readout. Starting one needs experiments.enabled. See CLI commands.
• Plugins (orbit plugin). A plugin can add its own tools, jobs, routines, auto-tasks, skills, and CLI commands. Plugins run sandboxed under explicit permission grants, and orbit plugin scaffold generates a starter.
• Agent skills. Three skills ship with Orbit: orbit (everyday task work), orbit-orchestrate (backlog and dispatch), and orbit-setup (machine and repo configuration). orbit init links them into your agents.

You can adopt these one at a time. The task layer and audit log work from day one. Parallel drains, auto-tasks, and plugins switch on when you want them.