Switchroom Install

Install Switchroom

When the user asks to install, set up, bootstrap, or get started with switchroom — or when they're new to switchroom and want to know where to begin — walk them through this flow. Switchroom turns a Linux server + their Claude Pro/Max subscription into always-on Claude Code agents reachable from Telegram.

Switchroom v0.7+ ships as a self-contained static binary (no host bun or node runtime required) and runs the agent fleet in Docker containers pulled from GHCR. The two host dependencies are: docker (engine 24+ with the compose v2 plugin) and the claude Code CLI (used for OAuth login against your Pro/Max subscription).

Step 0 — Detect existing install

Before doing anything, check whether switchroom is already installed:

command -v switchroom && switchroom --version 2>/dev/null

If switchroom is present, tell the user it's already installed and then — regardless — run the dependency audit in Step 2 so they see the state of docker and claude. After the audit, offer switchroom setup (re-run the wizard), switchroom doctor (diagnose), or switchroom agent list (see what's running). Do not reinstall switchroom itself without explicit confirmation.

Step 1 — Verify prerequisites

Switchroom requires Linux with Docker (Ubuntu 24.04 LTS canonical; ≥4GB RAM):

. /etc/os-release && echo "$PRETTY_NAME"
free -h | awk '/^Mem:/ {print $2}'
uname -m

If the user is on macOS or Windows, stop and explain: switchroom's release-validated production runtime is Linux. macOS (Docker Desktop) works for development but isn't yet release-gated. Windows users need WSL2.

Step 2 — Install host dependencies

Only install what's missing. Check each first:

# Docker
command -v docker || echo "MISSING: docker"
docker compose version >/dev/null 2>&1 || echo "MISSING: docker compose v2"

# Claude Code CLI (used inside agent containers and for the initial OAuth flow)
command -v claude || echo "MISSING: claude"

For anything missing:

# Docker (Ubuntu/Debian)
sudo apt update && sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"   # log out/in or `newgrp docker` to apply

# Claude Code CLI (needs Node 20.11+)
npm install -g @anthropic-ai/claude-code

Important: After usermod -aG docker, the user needs a new shell for group membership to apply. Mention this explicitly.

Step 3 — Install the switchroom binary

The recommended path is the static-binary one-liner — auto-detects platform/arch, downloads the matching pre-built binary from the latest GitHub release, verifies its SHA256, and installs to /usr/local/bin (or ~/.local/bin if not writable):

curl -fsSL https://github.com/switchroom/switchroom/raw/main/install.sh | sh

Verify:

switchroom --version

(For development against a source checkout, git clone + bun install + bun link still works — see docs/operators/install.md. Don't suggest the source path for first-time users.)

Step 4 — Run setup wizard

switchroom setup is an interactive wizard that wires the operator's Telegram bot token, sets up the vault, and scaffolds a first agent. DM-only by default — no forum chat ID required up front. It requires a terminal the user controls — if you're running inside an agent session, you cannot drive it yourself. Tell the user:

Run switchroom setup in your own terminal. It'll ask for your Telegram bot token and walk you through creating your first agent. Come back when it finishes and I can verify with switchroom doctor.

Step 5 — Apply and bring up the fleet

After switchroom setup completes, three commands take you from config to a running fleet:

switchroom apply
docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml pull
docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d --remove-orphans

switchroom apply reconciles every agent declared in switchroom.yaml and writes ~/.switchroom/compose/docker-compose.yml. The CLI deliberately does not run docker for you — operators own the bring-up. The first pull fetches the 5 GHCR images (~1-2 GB total); subsequent pulls are layer-only.

Step 6 — Verify

switchroom doctor
switchroom agent list

If switchroom doctor reports healthy and at least one agent is listed, installation is complete. Offer to invoke the switchroom-status or switchroom-health skill for a deeper look.

Optional follow-up: share one Anthropic account across multiple agents

This is the default. One OAuth flow per Anthropic account, then every agent in the fleet inherits the fleet-wide active account — no per-agent OAuth round. The auth-broker handles refresh and credential fanout automatically. See switchroom-manage (Anthropic accounts section) and docs/auth.md for the bootstrap flow. Flag this as soon as they ask "how do I add another agent?".

What not to do

• Do not run switchroom setup non-interactively or pipe input to it — it's designed for a human.
• Do not edit the vault (~/.switchroom/vault/) or any file under ~/.switchroom/ directly. Use the CLI.
• Do not run docker build on the operator's host. The fleet images are published on GHCR; switchroom apply writes a compose file that pulls them.
• Do not suggest the legacy switchroom up / switchroom init verbs — they were removed. NOTE: switchroom update is current and canonical — it is the one-shot upgrade path (pull images + apply + recreate + doctor); recommend it for "how do I update". A fresh install/redeploy is switchroom apply && docker compose pull && docker compose up -d.
• Do not reinstall over an existing install without asking. If the user wants a clean slate, have them run switchroom uninstall first (or confirm they want to blow away ~/.switchroom/).

Source: switchroom/switchroom — distributed by TomeVault.