Installation

You need Node 24.19 or newer and git on the machine running the server. Check both:

node --version
git --version

Install from GitHub Packages

The package owner must grant your GitHub account read access. Create a classic personal access token with read:packages. Add these lines to your home ~/.npmrc, replacing the placeholder with your own token:

@flashingpumpkin:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<token>

npm install --global @flashingpumpkin/orbital
orbital serve --version

Alternatively, use pnpm. Run pnpm setup and open a new shell if pnpm has no global bin directory. Allow the native SQLite dependency to build:

pnpm add --global --allow-build=better-sqlite3 @flashingpumpkin/orbital

Authenticate a harness

Choose one harness. Orbital does not install external harness CLIs for you.

Harness	Setup
Claude	The Agent SDK includes its CLI. Install the standalone Claude Code command for first-time login if you do not already have it. Run claude and follow the browser login on the server machine. Keep ANTHROPIC_API_KEY unset to use your subscription login.
Codex	Install the Codex CLI, run codex login, and check codex --version in the shell that starts Orbital.
OpenCode	Install OpenCode, run opencode auth login for your provider, and check opencode --version.

For the Codex path, install and sign in before starting Orbital:

npm install --global @openai/codex
codex login
codex --version

For OpenCode:

npm install --global opencode-ai
opencode auth login
opencode --version

See the official Claude Code setup, Codex CLI and OpenCode authentication instructions for installation on your operating system.

For workflows reading GitHub, supply GH_TOKEN, then GITHUB_TOKEN, or an existing gh login. A token saved in server Settings takes precedence; otherwise the server uses those sources in that order. Repository read access is separate from the package registry token.

Start and upgrade

orbital serve

Open the address printed by the server. It binds to loopback by default and opens your browser. --port 42121 fixes the port, --no-open suppresses browser opening, and --bind changes the listening address. The server has no authentication, so keep it on loopback for local use.

Upgrade with npm update --global @flashingpumpkin/orbital, then restart the server. The data directory survives upgrades and uninstalling. A build older than the database’s migrations refuses to start; retain a backup before attempting a downgrade.

Continue with getting started.