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.

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.9.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: 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).

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