# Server Setup

Choose between **Docker** (fastest on any OS) or a **Native Linux** installation on Ubuntu 24.04 LTS to run `sandboxed.sh` (the former name of the project, now the backend to the Orb clients) with native `systemd-nspawn` isolation and cgroup slices.

## Option 1: Docker (5 minutes)

Docker bundles the Rust backend, web admin console, Caddy reverse proxy, and core CLIs in one container. See the [Docker Install](/install-docker) guide:

```bash
git clone https://github.com/Th0rgal/orb.git
cd orb
cp .env.example .env
# Edit .env: set DASHBOARD_PASSWORD and JWT_SECRET
docker compose up -d
```

## Option 2: Native Ubuntu 24.04 LTS (Production)

### 1. Install system dependencies

```bash
apt update && apt install -y \
  ca-certificates curl git jq unzip tar python3 python3-yaml \
  build-essential pkg-config libssl-dev \
  systemd-container debootstrap

# Install Bun & Node.js 20+
curl -fsSL https://bun.sh/install | bash
install -m 0755 /root/.bun/bin/bun /usr/local/bin/bun

# Install Rust
curl -fsSL https://sh.rustup.rs | sh -s -- -y
source /root/.cargo/env
```

### 2. Install coding-agent harnesses

Missions run coding-agent CLIs **per workspace** (no central OpenCode server is required). Install the harnesses you plan to use on the host or via the managed fleet updater (`scripts/update-node-harnesses.py`):

- **Claude Code**: `npm install -g @anthropic-ai/claude-code`
- **Codex**: `npm install -g @openai/codex`
- **Antigravity (`agy`)**: Install from [antigravity.google/docs/cli/install](https://antigravity.google/docs/cli/install/) and sign in as the execution user (`agy` / `agy models`)
- **OpenCode**: `curl -fsSL https://opencode.ai/install | bash -s -- --no-modify-path && install -m 0755 /root/.opencode/bin/opencode /usr/local/bin/opencode`
- **Grok**: Install the Grok CLI and authenticate (`grok login --device-auth`)

### 3. Build the backend and unified MCP companion

Always use debug `cargo build` (not `--release`) for the I/O-bound control plane:

```bash
mkdir -p /opt/sandboxed_sh
cd /opt/sandboxed_sh
git clone https://github.com/Th0rgal/orb.git repo
cd repo

cargo build --bin sandboxed-sh --bin sandboxed-mcp --bin sandboxed-node --bin palomactl
install -m 0755 target/debug/sandboxed-sh /usr/local/bin/sandboxed-sh
install -m 0755 target/debug/sandboxed-mcp /usr/local/bin/sandboxed-mcp
install -m 0755 target/debug/sandboxed-node /usr/local/bin/sandboxed-node
install -m 0755 target/debug/palomactl /usr/local/bin/palomactl
```

### 4. Configure environment

Create `/etc/sandboxed-sh/sandboxed-sh.env` (the backend also probes `/etc/open_agent/open_agent.env` for legacy installs):

```bash
mkdir -p /etc/sandboxed-sh
cat > /etc/sandboxed-sh/sandboxed-sh.env << 'EOF'
HOST=127.0.0.1
PORT=3000
WORKING_DIR=/root
DEV_MODE=false
DASHBOARD_PASSWORD=change-me-to-something-strong
JWT_SECRET=change-me-to-a-long-random-string
SANDBOXED_OAUTH_OWNER=cli-proxy
EOF
chmod 0600 /etc/sandboxed-sh/sandboxed-sh.env
```

### 5. Create the systemd service and resource slice

Create `/etc/systemd/system/sandboxed-sh.service`:

```ini
[Unit]
Description=sandboxed.sh (Orb) Control Plane
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/sandboxed-sh/sandboxed-sh.env
ExecStart=/usr/local/bin/sandboxed-sh
WorkingDirectory=/root
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
systemctl daemon-reload
systemctl enable --now sandboxed-sh.service
```

Put Nginx or Caddy in front of `127.0.0.1:3000` with TLS (for example at `https://orb.thomas.md` or `https://agent-backend.example.com`).

## Connecting Clients

| Client | How to connect |
| --- | --- |
| **Orb Desktop (macOS)** | Run `pnpm install && pnpm tauri dev` in `orb/`, then enter your server URL in **Settings → Client → Backend** |
| **Orb iOS** | Build `ios_dashboard/` via XcodeGen (`SandboxedDashboard` scheme, product name `Orb`) and sign in to your server URL |
| **Web Admin Console** | Deploy `dashboard/` to Vercel (`NEXT_PUBLIC_API_URL`) or run `bun dev` locally |
| **Hermes Coordinator** | Point Hermes's MCP server config at `/usr/local/bin/sandboxed-mcp` |

For full bare-metal details (cgroup slices, disk-backed container `/tmp`, CLIProxyAPI Plus, and Tailscale), see [`docs/install-native.md`](https://github.com/Th0rgal/orb/blob/master/docs/install-native.md).