Install Orbit

Install the CLI, then let your agent’s orbit-setup skill set up your repository. Every step is also below to do by hand.

Prerequisites

• macOS or Linux, on x64 or arm64. On Windows, run Orbit inside a WSL2 Linux distribution: the Windows WSL2 guide covers the distribution, sandbox, MCP clients and the scheduler there. That path has not been run on a Windows host yet.
• Node 18 or newer, for the npm install.
• At least one signed-in agent CLI, such as Claude Code or Codex. Orbit runs every agent step through one. The setup explorer lists the supported CLIs.
• The GitHub CLI (gh), signed in, if you want pull requests.

Install

npm install -g @orbit-tools/cli
orbit init

The package downloads the matching native binary and puts orbit on your PATH. orbit init asks for a machine name and a task-ID prefix, detects your agent CLIs, links Orbit’s skills into your agents, and on Linux prepares the sandbox.

Releases also attach a desktop app, a native window for the dashboard, to the GitHub release: .deb and .AppImage bundles for Linux on x64 and arm64. The app starts orbit web serve from your installed orbit, so it needs the CLI install above. macOS bundles are attached only when the release was built with Apple signing credentials, so a release may have none. See Use the desktop app for first launch, tray controls, and fleet notifications.

Install as an agent plugin

To give a single agent Orbit’s MCP tools and skills without installing the CLI on PATH, add the plugin. It launches the pinned npm CLI. The dashboard and cross-agent workspace setup still need the CLI install above.

# Claude Code
/plugin marketplace add constellation-works/orbit
/plugin install orbit

# Codex CLI
codex plugin marketplace add constellation-works/orbit --ref agent-main
codex plugin add orbit@orbit

# Cursor (local plugin from a checkout)
mkdir -p ~/.cursor/plugins/local && ln -sfn "$(pwd)/plugin" ~/.cursor/plugins/local/orbit

In Claude Code, the plugin also adds an in-session UI with a live task band, interactive board, and ship view. See Use the Claude Code mod to learn how to use it.

Want to be walked through setup? Ask your agent to set up Orbit for this repo; the bundled orbit-setup skill takes it from there.

Let your agent set it up

Recommended

Open your agent in the repository and ask it to set up Orbit for this repo.

The orbit-setup skill checks what is already in place, registers the repository, connects your agent over MCP, checks your agent CLIs and the sandbox, and runs orbit doctor. It asks only for choices it cannot infer, such as the branch pull requests should target. When it finishes, start a fresh agent session so the Orbit tools load.

Use the same skill for later changes: adding a provider, scheduling work, upgrading, or fixing a failing orbit doctor.

Set up by hand

These are the steps the skill runs. Use them to set up by hand, or to see what the skill did.

Initialize state

orbit init
cd <repo>
orbit workspace init --mcp

orbit init sets up this machine under ~/.orbit/. It asks for a machine name, which you can rename later, and a task-ID prefix of 2–5 uppercase letters, such as ABC, which can never change (ORB and ADR are reserved). For an unattended setup, pass both:

orbit init --non-interactive --machine-name build-01 --task-prefix ABC

On Linux, an unattended orbit init never waits for a password, so it prepares the sandbox only as root or with passwordless sudo. Otherwise it warns and still seeds Orbit, and agent runs stay blocked until orbit doctor providers reports the sandbox ready.

orbit workspace init registers the repository and keeps its state under .orbit/. --mcp connects your agent clients with operator authority, which lets them ship tasks and run governed operations. Plain orbit mcp init registers an agent-only connection instead; see Connect Your Agent.

By default, pull requests target the branch checked out when you run orbit workspace init, or main if none is. Add --base-branch <branch> to choose another, or --ship-mode local to merge in place instead of opening pull requests.

If a distribution supplies a workspace preset, apply it with orbit workspace init --preset <file>. The TOML preset selects shipped routines and auto-tasks, enables definitions from an already enabled plugin, and sets workspace config. Orbit validates the whole file before writing anything. See Workspace presets.

Prepare the sandbox

Orbit runs each agent in an OS-level sandbox: sandbox-exec on macOS, which needs no setup, and Bubblewrap on Linux, which fails closed without a trusted Bubblewrap that supports --bind-fd.

On Linux, orbit init prepares the sandbox. It probes Bubblewrap as your account and, only if that fails, installs it through the distribution’s package manager, asking for your password. Where the distribution’s Bubblewrap is missing or too old for Orbit, as on Ubuntu 22.04, it installs the signed Bubblewrap published with each Orbit release to /usr/local/libexec/orbit/bwrap instead. On Ubuntu 24.04 it also loads the packaged AppArmor rule. Run orbit init as the account that will run Orbit, not through sudo.

A run that fails with bwrap: setting up uid map: Permission denied points to this step, not your task. The Linux sandbox runbook covers which distributions are prepared automatically, container images, and the fix for each failure.

Configure and check

orbit init writes ~/.orbit/config.toml with the built-in crews, enabling those whose agent CLI it detects. It picks a default from those available; with none detected, enable a crew before dispatching. To pick a different default, choose an enabled crew and set workflow.default_crew. Seed the workspace config on its first edit, then check the workspace:

orbit config set --seed-from-global workflow.default_crew opus
orbit doctor

orbit doctor checks config, database, disk, indexes, locks, and runs, and orbit doctor providers shows whether each agent CLI and the sandbox are ready. Configuration lists every setting.

Stay current

Ask your agent to upgrade Orbit; the orbit-setup skill checks for running Orbit processes first. To upgrade by hand, stop running Orbit sessions and orbit web serve, then run:

npm install -g @orbit-tools/cli@latest

orbit update --check tells you whether a newer release is out. npm owns this install, so orbit update prints the npm command instead of replacing the binary. Pending state migrations apply the next time Orbit opens the workspace. Upgrade every host together for distributed work, and restart long-lived MCP servers too: older clients cannot write after the current handoff-storage migration.