> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt. # Install Orbital > Install the Mac app or the orbital command, then sign in to a harness You install Orbital, then sign in to at least one harness, the coding agent that does the work: Claude Code, Codex or OpenCode. At the end, **Settings > Harnesses** shows a harness ready to take a run. About 5 minutes. ## Before you start On a Mac, you need nothing else. Orbital.app starts its own server, updates itself and needs neither npm nor Node. On Linux or Windows, you install the `orbital` command with npm and run `orbital serve`. You need Node 24.19 or newer and `git`, and an invitation to the npm package during the beta. ## 1. Install Orbital **Mac app** 1. **Download the disk image for your Mac.** These addresses always serve the newest release: [Apple Silicon](https://releases.runorbital.dev/macos/Orbital-latest-arm64.dmg) or [Intel](https://releases.runorbital.dev/macos/Orbital-latest-x64.dmg). 2. **Drag Orbital to Applications.** Open the disk image and drag Orbital to the **Applications** folder. 3. **Open Orbital.** Open it from **Applications** or the Dock. The first launch asks you to set up a project. ![The first-launch wizard with the heading Give your agents a place to work, the steps Welcome, Project and First run, and a Set up a project button.](/screenshots/first-launch.webp?v=5ece35762f) *The first launch walks you through adding a project.* The app is signed and notarised. It reads your login shell's `PATH`, so it finds `git`, `claude`, `codex` and `opencode` where your terminal finds them. It serves on port 42121, or on a free port when another program holds that one. **Command line** The Mac app carries the `orbital` command. To use it from a terminal: 1. **Open the command line settings.** Open **Settings > Command line and skills**. 2. **Install the command.** Under **The orbital command**, choose **Install**. You can also choose **Orbital > Install Command Line Tool** from the menu bar. 3. **Give your password if asked.** Enter your administrator password if your Mac asks for it. 4. **Check the command.** Open a new terminal and run `orbital --help`. This links `/usr/local/bin/orbital` to the command inside the app. After the app updates, the command runs the new release without another install. `orbital run start` then starts runs in the open app. [The orbital command](/command-line/) explains every command. **npm** npm access is by invitation during the beta. The Mac app is the main way to get Orbital, and npm releases are on hold. To ask for access, contact the Orbital team through [runorbital.dev](https://runorbital.dev) and give your GitHub account name. Use npm on Linux or Windows, or on a Mac without the app. You need Node 24.19 or newer and `git`. Check them: ```sh node --version git --version ``` The package is `@flashingpumpkin/orbital` on GitHub Packages, which needs a token even to read it. Once your invitation gives your GitHub account read access: 1. **Create a token.** Create a [classic personal access token](https://github.com/settings/tokens) with only the `read:packages` scope. 2. **Add the registry to npm.** Add these two lines to `~/.npmrc`, with your token in place of ``: ```ini title="~/.npmrc" @flashingpumpkin:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken= ``` 3. **Install and check.** ```sh npm install --global @flashingpumpkin/orbital orbital --version ``` 4. **Start the server.** ```sh orbital serve ``` The server prints its address, `http://127.0.0.1:42121/` unless you change the port, and opens it in your browser. It listens only on your own machine. `orbital app` opens the same app in a window of its own instead. [The orbital command](/reference/command/#orbital-serve) lists the flags. With pnpm, allow Orbital's storage dependency to build: `pnpm add --global --allow-build=better-sqlite3 @flashingpumpkin/orbital`. This registry token only downloads the package. Orbital never reads it. Workflows that read GitHub use a separate GitHub token; see [Settings](/reference/settings/#github). :::caution The server has no login of its own. Keep it on your own machine unless you protect the network yourself. ::: ## 2. Install and sign in to a harness Orbital runs the harnesses you install yourself, and ships none of them. Install at least one. Sign in before you start Orbital, because a running server does not see credentials you export later. **Claude Code** Install it with `npm install -g @anthropic-ai/claude-code@latest`. Orbital works with version 2.1.280 or newer. To sign in, run `claude` and follow the login. Leave `ANTHROPIC_API_KEY` unset to use your subscription. The [Claude Code setup guide](https://code.claude.com/docs/en/setup) covers installing it on your system. **Codex** Install it with `npm install -g @openai/codex@latest`. Orbital works with version 0.156.0 or newer. To sign in, run `codex login`. The [Codex guide](https://learn.chatgpt.com/docs/codex/cli) covers installing it on your system. **OpenCode** Install it with `npm install -g opencode-ai@latest`. Orbital works with version 1.18.0 or newer. To sign in, run `opencode auth login` for your provider. The [OpenCode guide](https://opencode.ai/docs/cli/#auth) covers installing it on your system. ## 3. Check that Orbital finds the harness Check the harness in a terminal first: `claude --version`, `codex --version` or `opencode --version`. Then open **Settings > Harnesses** in Orbital. The status table shows whether each harness is installed, whether it is new enough and whether it is signed in. ![Settings, Harnesses page with a status table showing whether Claude, Codex and OpenCode are installed and signed in, followed by Claude's settings for turned on, program, default model, default effort and environment variables.](/screenshots/settings-harnesses.webp?v=6446e71ff0) *The status table shows which harnesses are ready.* Orbital looks for each harness in this order: 1. The program set under **Program** in **Settings > Harnesses**. 2. `claude`, `codex` or `opencode` on the `PATH` of your login shell. The Mac app reads that `PATH` from your shell when it opens, so Orbital finds any harness you can start in a terminal. A harness Orbital cannot find reads "Not installed", with the command to install it. Install it, then choose **Check again**. [Harnesses and models](/harnesses/) explains more. ## Upgrade Orbital **Mac app** The app checks for a new release when it starts and every hour. It downloads an update in the background and says "Orbital \ is downloading". When the update is ready, choose **Restart to update**, or it installs the next time you quit. **Settings > About** shows the version you are running, the last check and its result, and a **Check for updates** button. Orbital updates itself only from the **Applications** folder. Opened from the disk image, it says "Move Orbital to Applications to get updates". ![Settings, About page showing the running version, its updates and the path of the settings file.](/screenshots/settings-about.webp?v=ae05abacce) *About shows the version you run and whether an update is waiting.* **Command line** The `orbital` command installed from the Mac app is a link to the command inside the app. It updates with the app, and runs the new release without another install. **npm** The npm package checks for a newer release when the server starts and once an hour. In a terminal, `orbital serve` asks before it starts: ```text Orbital is available. You are running . Update before starting? [Y/n] ``` A server that is already running shows "Orbital \ is available." with an **Update and restart** button. Runs that are working carry on by themselves after the restart. You can also run `npm update --global @flashingpumpkin/orbital` and restart the server. Your data in `~/.orbital` survives upgrades and uninstalling. :::caution An older release refuses run history that a newer one has updated. Keep a copy of `~/.orbital/run-history.db` before you go back to an older release. ::: ## Next steps - [Start your first run](/get-started/first-run/): add a project and run `explain-repo`. - [Harnesses and models](/harnesses/): how Orbital picks and starts each harness. - [Command line](/command-line/): what each subcommand does. - [Troubleshooting](/troubleshooting/): fixes when the app or a harness will not start.