# Getting Started with Orb

This guide walks you through connecting **Orb** (macOS and iOS) to your **sandboxed.sh** backend (`sandboxed.sh` is the former name of the project and is now the backend to the Orb clients), configuring your subscriptions and harnesses, and launching your first coding agent.

## 1. Prerequisites

1. **A running backend (`sandboxed-sh`)**:
   - **Docker**: `http://localhost:3000` (see [Docker Install](/install-docker))
   - **Remote Linux server**: e.g., `https://orb.thomas.md` or `https://agent-backend.example.com` (see [Server Setup](/setup))
2. **Orb Client**:
   - **macOS Desktop (`orb/`)**: Tauri v2 + SolidJS native app (`pnpm install && pnpm tauri dev`)
   - **iOS App (`ios_dashboard/`)**: SwiftUI app generated via XcodeGen (`xcodegen generate && open SandboxedDashboard.xcodeproj`)
   - **Web Admin Console (`dashboard/`)**: Bundled in Docker on port 3000 or deployed separately

<DesktopShowcase
  src="/images/orb-desktop.webp"
  alt="Orb on macOS"
  caption="Orb Desktop on macOS: projects sidebar, live agent transcript, and synchronized project files."
/>

## 2. Connect to Your Backend

### On macOS (Orb Desktop)

1. Open **Settings** (`⌘,`) → **Client**.
2. Under **Backend**, enter your server URL and dashboard password (or username + password in multi-user mode).
3. Click **Connect**. Orb stores the connection in local storage and synchronizes your projects, machines, and model catalog.

### On iOS (Orb iOS)

1. Launch **Orb** on your iPhone or iPad.
2. Enter your **Server URL** and **Password** in the connection sheet, then tap **Connect**.
3. Tap the profile icon in the top bar at any time to switch servers or inspect **Backend**, **Providers**, and **Machines**.

<IosShowcase />

## 3. Configure Harnesses & Subscriptions

### Local Harnesses (macOS)

Open **Settings** (`⌘,`) → **Client** → **Local agents** and click **Scan**. Orb checks your local `PATH` (or custom binary overrides) for installed coding CLIs:

- **Claude Code** (`claude`)
- **Codex** (`codex`)
- **Antigravity** (`agy`, discovers account models via `agy models`)
- **OpenCode** (`opencode`)
- **Grok** (`grok`)

Local runs use the credentials and sessions already configured on your Mac without copying server tokens onto your laptop.

### Subscriptions & Inference Providers

Open **Providers** (`⌘4` on macOS, or **Settings → Providers** on iOS) to manage model inference for server and fleet runs:

- **OAuth Subscriptions (CLIProxyAPI Plus)**: Sign in to Anthropic (Claude), OpenAI (Codex/ChatGPT), xAI, Kimi, or Google Antigravity. When `SANDBOXED_OAUTH_OWNER=cli-proxy` is active, CLIProxyAPI owns token refresh and multi-account rotation so parallel missions never race on refresh tokens.
- **API Keys**: Add standard API keys for OpenRouter, Anthropic, OpenAI, xAI, MiniMax, Z.AI, or Google.
- **Model Routing (`Settings → Routing`)**: Define ordered fallback chains (`builtin/smart`, `builtin/fast`, or custom chains) and inspect live account health and fallback events.

## 4. Create a Project and Launch an Agent

<DesktopShowcase
  src="/images/orb-setup.webp"
  alt="Creating an agent in Orb"
  caption="Configuring a new agent run in Orb with placement, harness, model, and effort controls."
/>

1. Press `⌘5` (or click **Projects** in the sidebar) to create a project with a custom color.
2. Press `⌘N` (or `⌘1`) to open the **New Agent** composer, or `⌘2` for **Cloud agent**:
   - **This computer**: Runs a local CLI on your Mac in `~/.orb/local-runs/<mission-id>` (or a custom directory) while syncing the transcript and `@context` to the server.
   - **Core / Remote machine**: Runs in a host workspace or isolated `systemd-nspawn` container on your server or a registered `sandboxed-node` machine.
   - **Cloud agent**: Starts a durable **Hermes** coordinator conversation, **Grok Bot** run, or **Cursor Cloud** repository agent.
3. Choose the **Harness**, **Model**, **Effort** (`low`, `medium`, `high`, `xhigh`), and optional **Cyber Access** (`Standard`, `Daybreak`, `Automatic` for Codex).
4. Optional prefixes in the composer:
   - `/goal <objective>`: Launches a multi-turn autonomous goal run.
   - `/plan <task>`: Launches native interactive planning mode (supported on Claude Code and Codex).
   - `@context/<file>`: References shared project context files synchronized in Finder.

## 5. Desktop Keyboard Shortcuts

| Shortcut | Action |
| --- | --- |
| `⌘1` / `⌘N` | New agent |
| `⌘2` | Cloud agent |
| `⌘3` | Machines |
| `⌘4` | Providers |
| `⌘5` | Focus projects tree (`↑`/`↓` navigate, `Enter` opens) |
| `⌘B` | Toggle sidebar |
| `⌘J` | Toggle workspace & context Files panel |
| `⌘⇧J` | Toggle `/btw` side-agent panel |
| `⌘P` | Quick file palette |
| `⌘F` / `⌘⇧F` | Find in transcript / Search in files |
| `⌘/` | Switch Markdown preview / source |
| `⌘,` | Settings (Client & Routing) |