Installation

This page takes you from nothing to the Command Center open in your browser. The whole stack runs in Docker, so the only things you install on the host are Docker itself and (for the default Claude backend) the Claude Code CLI.

Fastest path: one command

If you just want the pre-built registry images up with sane defaults, skip straight to make quickstart after step 1 and step 2 below (authenticate Claude Code, clone the repo) — it does steps 3 and 4 for you: scaffolds a fresh .env from .env.example with the required secrets freshly generated (or validates an existing one, untouched), then pulls and brings up docker-compose.registry.yml and runs a doctor-style readiness sweep, failing loud with the exact next command if any stage doesn't check out.

bash
1make quickstart

It's fully idempotent — re-running it never touches an existing .env. The step-by-step walkthrough below is what it automates, useful when you want to see or control each piece yourself (a pinned version, Grok/Codex/Gemini/Kimi instead of Claude, custom host paths).

1. Authenticate the model backend

By default every agent runs on Anthropic Claude, using the Claude Code session on your host rather than a metered API key. Authenticate once:

bash
1npm install -g @anthropic-ai/claude-code2claude   # opens a browser to log in; creates ~/.claude

That ~/.claude directory is mounted read-only into the orchestrator, which hands it to each agent container. If you'd rather run the workforce on Grok, skip this and see Optional: run on Grok below.

2. Get the code

bash
1git clone https://github.com/rennf93/roboco.git2cd roboco3cp .env.example .env

3. Set the two required secrets

Open .env and set these two — the orchestrator refuses to start without the first, and Docker deployments need the second:

bash
1# Encrypts every per-project GitHub token at rest (Fernet). REQUIRED.2ROBOCO_ENCRYPTION_KEY=3 4# Signs the per-agent auth tokens (HMAC). REQUIRED for docker compose.5ROBOCO_AGENT_AUTH_SECRET=

Generate each one:

bash
1# ROBOCO_ENCRYPTION_KEY2python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'3 4# ROBOCO_AGENT_AUTH_SECRET5python -c 'import secrets; print(secrets.token_hex(32))'
Keep `ROBOCO_ENCRYPTION_KEY` safe and stable

This key encrypts the GitHub tokens you'll store per project. If you lose it or change it later, every stored token becomes undecryptable and must be re-entered. Back it up with your other secrets, and never commit .env.

Everything else in .env.example has a working default for a local Docker run. On a NAS or remote server you'll also set the host-path variables (ROBOCO_HOST_PROJECT_DIR, ROBOCO_HOST_CLAUDE_DIR, ROBOCO_DATA_DIR) — those are covered in the deployment reference.

4. Bring up the stack

You have two ways to get the images. Both start from the clone above.

Every release publishes all RoboCo images to both the GitHub Container Registry and Docker Hub, so you can run the full stack without building anything:

bash
1docker compose -f docker-compose.registry.yml pull2docker compose -f docker-compose.registry.yml up -d

Pick the registry and version with two variables (defaults shown):

bash
1ROBOCO_REGISTRY=ghcr.io/rennf93   # or docker.io/renzof932ROBOCO_VERSION=latest             # or a pinned release, e.g. 0.20.0

The orchestrator pulls and spawns the matching pre-built agent images on demand — no build toolchain on your host.

The first start does real work: it pulls the local models into Ollama (the embedding model is quick; the local LLM is a couple of minutes), then the orchestrator waits for them, runs the database migrations itself, and indexes its knowledge base. You don't run migrations by hand — the stack brings its own schema up to date on every boot.

5. Watch it come up

bash
1docker compose logs -f orchestrator

Wait until the orchestrator reports it's serving, then open:

text
1http://localhost:3000

That's the Command Center — per-cell health, the CEO approval queue, live metrics, and recent activity. The company is up; it's just idle because you haven't given it a repository or a task yet.

One address for everything

nginx is the only externally-exposed service. It serves the panel and proxies /api and /ws to the orchestrator, so the browser sees a single origin at :3000. You generally won't hit the orchestrator's own port directly.

Next

→ Register your first project — point RoboCo at a repository it's allowed to work on.

Optional: run on Grok instead

RoboCo can run the entire workforce on xAI Grok using xAI's official grok CLI on a SuperGrok subscription — no metered API key, so a run can't stall mid-task on exhausted credits.

bash
1grok login                     # once, on the host — creates ~/.grok/auth.json

Then in .env:

bash
1ROBOCO_HOST_GROK_DIR=/home/youruser/.grok   # the real host ~/.grok to mount in2# ROBOCO_GROK_AGENT_IMAGE=roboco-agent-grok:latest3# ROBOCO_GROK_CLI_MODEL=grok-build4# ROBOCO_GROK_REASONING_EFFORT=        # low|medium|high|xhigh|max (empty = model default)

The orchestrator keeps the short-lived Grok token refreshed for you, so agents don't hang on an expired login. Which agents run on which backend is set on the Settings → AI Providers page — that, and the per-role model assignments, are covered in the models section.

Optional: run on Codex instead

RoboCo can run its delivery agents (not the interactive Intake/Secretary chats — see Run on Codex) on OpenAI's Codex CLI using a ChatGPT subscription — no metered API key.

bash
1codex login                     # once, on the host — creates ~/.codex/auth.json

Then in .env:

bash
1ROBOCO_HOST_CODEX_DIR=/home/youruser/.codex   # the real host ~/.codex to mount in2# ROBOCO_CODEX_CLI_MODEL=gpt-5.3-codex

Set the Codex routing mode (or pin individual agents) on Settings → AI Providers, same as Grok above.

Optional: run on Gemini instead

RoboCo can also run its delivery agents on Google's Gemini CLI using an OAuth login — no metered API key. See Run on Gemini for the same V1 delivery-roles-only scope.

bash
1gemini                          # once, on the host — interactive OAuth login, creates ~/.gemini

Then in .env:

bash
1ROBOCO_HOST_GEMINI_DIR=/home/youruser/.gemini   # the real host ~/.gemini to mount in2# ROBOCO_GEMINI_CLI_MODEL=gemini-2.5-pro

Set the Gemini routing mode (or pin individual agents) on Settings → AI Providers.

Optional: run on Kimi instead

RoboCo can also run its delivery agents (not the interactive Intake/Secretary chats — see Run on Kimi) on Moonshot AI's Kimi K3 using a Kimi subscription — no metered API key, authenticated by a device-code OAuth login.

bash
1kimi login                     # once, on the host — device-code OAuth, creates ~/.kimi-code

Then in .env:

bash
1ROBOCO_HOST_KIMI_DIR=/home/youruser/.kimi-code   # the real host ~/.kimi-code to mount in2# ROBOCO_KIMI_CLI_MODEL=kimi-code/k3

Set the Kimi routing mode (or pin individual agents) on Settings → AI Providers.

Optional: secure mode

On a trusted LAN, RoboCo runs in header-trust mode by default: requests identify the caller by role headers, with no token required. That's fine on a private network and is the intended setup.

If you need to harden it so an agent can't spoof another's role, set ROBOCO_AGENT_AUTH_REQUIRED=true, keep your ROBOCO_AGENT_AUTH_SECRET, and generate the panel's CEO token with make panel-token into ROBOCO_PANEL_AGENT_TOKEN. nginx injects that token so the panel keeps working without the browser holding the signing secret. The full security model is in the Configure & Deploy reference.

Warning

Don't expose RoboCo to the public internet as-is. It's built to run on a trusted private network (homelab / LAN).

Optional: cloud auth

Secure mode above hardens the agent fleet's headers. If you also want the CEO's own browser session to require a login — the case for exposing the panel beyond your LAN — set ROBOCO_CLOUD_AUTH_ENABLED=true plus ROBOCO_CLOUD_AUTH_EMAIL / ROBOCO_CLOUD_AUTH_PASSWORD / ROBOCO_CLOUD_AUTH_SECRET (the orchestrator refuses to start if the secret is missing while the flag is on). This is a separate concern from the agent HMAC token above; see Cloud auth for the full setup.

Danger

The session cookie is secure-only, so this only works behind TLS — terminate HTTPS in front of RoboCo before you enable it.

Resources

RoboCo is light at runtime. Agent containers are spawned on demand and torn down when their work is done, so you rarely have more than a handful live at once.

At idle (full stack, no task running)RAM
Ollama (models loaded)~2.2 GB
Orchestrator~150 MB
Postgres / Panel / Redis / nginx~120 MB combined

The whole standing stack idles around ~2.5 GB, almost all of it Ollama. Under load — five agents working concurrently — the stack peaked around ~6.6 GB; even at full-fleet peak you stay well under ~10 GB. Storage is the larger footprint: the agent images all build from a shared base layer, so on disk they cost far less than their nominal sizes summed. docker system prune reclaims old image versions, stopped containers, and build cache.

bash
1docker stats        # live RAM / CPU per running container2docker system df    # image / container / build-cache disk usage

Running on the host (for hacking on RoboCo itself)

If you want to develop RoboCo's own code rather than just run it, you can run only the backing services in Docker and the app on your host. RoboCo's code needs Python 3.13+ (uv fetches it if needed):

bash
1uv sync2docker compose up -d postgres redis ollama   # backing services only3uv run alembic upgrade head                    # migrate the database4uv run python -m roboco.cli                    # API + orchestrator

llms.txt