simbos

The official SimbOS CLI. One command (simbos setup) signs you into SimbOS, auto-detects every AI tool installed on your machine (Claude Code, Codex, OpenCode, Claude Desktop), wires up their MCP configs to talk to your workspace, and registers the machine as a runner. After that, simbos start runs a small daemon that picks up agent jobs from the cloud and executes them locally.

Cross-platform: macOS, Windows, and Linux.

Install

npm install -g simbos
# or run without installing:
npx simbos@latest --help

Requires Node.js 20+.

Quick start

simbos setup            # one-time wizard: auth + connect tools + register
simbos start            # run the daemon (foreground)
simbos status           # show auth, runner, and per-tool MCP state

What simbos setup does

1. Sign in. Uses an OAuth Device Flow against https://app.simbos.io (override with SIMBOS_API_URL). Shows you a short code, opens your browser to confirm, and saves the access token to ~/.simbos/auth.json (mode 600).
2. Connect AI tools. Detects which of these are installed and wires each one's MCP config to point at SimbOS: | Tool | Config file | macOS | Windows | Linux | |---|---|---|---|---| | Claude Code | ~/.claude.json | yes | yes | yes | | Codex CLI | ~/.codex/config.toml | yes | yes | yes | | OpenCode | ~/.config/opencode/opencode.json (Mac/Linux) / %APPDATA%\opencode\opencode.json | yes | yes | yes | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) / %APPDATA%\Claude\claude_desktop_config.json (Win) | yes | yes | n/a |
3. Register the machine as a runner. Saves a runner-scoped token to ~/.simbos/runner-state.json.

Run as a background service

After simbos setup, install the runner as a system service so it auto-starts when your machine boots:

simbos service install

Manage:

simbos service status        # is it installed? running? last log lines
simbos service stop
simbos service start
simbos service uninstall
simbos service logs          # tail the last 50 lines of the log file

Logs go to ~/.simbos/runner.log. Works on macOS (launchd user agent), Linux (systemd user unit), and Windows (Task Scheduler at logon).

Per-tool commands

simbos connect claude-code           # connect just one
simbos connect --all                 # detect and connect everything installed
simbos connect codex --force         # overwrite existing config

simbos disconnect claude-desktop     # remove SimbOS from one tool
simbos disconnect --all              # remove SimbOS from every tool

simbos logout                        # revoke token + disconnect everything

connect is idempotent and writes config files atomically. disconnect only removes the simbos entry and leaves any other MCP servers alone.

Status

simbos status

Sample output:

SimbOS runner   ✓ online  · heartbeat ok
                · runner-id 3ddd-728b-...
                · workspace tonelotto-com

Auth            ✓ signed in · ~/.simbos/auth.json

Tools connected:
  ✓ Claude Code     1.2.5    (~/.claude.json)
  ✓ Codex CLI       0.4.1    (~/.codex/config.toml)
  ⋯ OpenCode        not installed
  ✓ Claude Desktop  -        (~/Library/Application Support/Claude/claude_desktop_config.json)

Daemon

simbos start
# or just `simbos` (default subcommand)

The daemon long-polls the SimbOS API for queued agent jobs, spawns Claude Code locally to execute them, and streams output back. Leave it running in a terminal (or run as a service / launchd plist / Windows service).

Legacy YAML config

The pre-0.2 flow used a hand-edited ~/.simbos/runner.yaml plus an API key, paired with simbos register. That path still works:

simbos register
simbos register --force

See git history for the legacy YAML schema. New users should prefer simbos setup.

Environment overrides

| Variable | Purpose | |---|---| | SIMBOS_API_URL | SimbOS API URL (default https://app.simbos.io) | | SIMBOS_MCP_URL / MCP_URL | MCP endpoint URL (default derived from API URL) | | SIMBOS_AUTH_STATE | Path to auth.json (default ~/.simbos/auth.json) | | SIMBOS_RUNNER_CONFIG | Path to runner.yaml (legacy) | | SIMBOS_RUNNER_STATE | Path to runner-state.json | | SIMBOS_RUNNER_LOG_LEVEL | debug / info / warn / error | | SIMBOS_RUNNER_CLAUDE_BIN | Override claude binary path |

Cross-platform notes

• Path resolution centralized in src/paths.ts: homeDir(), configHome(), appDataDir(name), localAppDataDir(name), expandHome(p). Connectors never embed ~/... strings directly.
• Atomic file writes: every config write goes to <file>.tmp, then rename(). A killed simbos mid-write never corrupts your existing AI-tool configs.
• Claude Desktop isn't shipped on Linux, so the connector reports "not installed" there and skips silently.

Troubleshooting

| Symptom | Fix | |---|---| | Not authenticated. Run \simbos setup` first.| Runsimbos setup| |claude: command not found(duringstart) | Install Claude Code CLI or set SIMBOS_RUNNER_CLAUDE_BIN| | Setup hangs at "Waiting for authorization" | Open the printed URL manually; the browser-launch is best-effort | |Authentication failedon heartbeat |simbos logout && simbos setup` | | Claude Desktop didn't pick up SimbOS | Restart the Claude Desktop app |

License

MIT