This is the operator reference for running RoboCo on a NAS or server. If you just want it up on your laptop, the install quickstart is faster — this page assumes you've done that once and now want the durable, server-side setup: the compose files, the host mounts agents need, where data lives, how to back it up, and how to harden it.

The three compose files

There are three tracked compose files, and they are not interchangeable:

docker-compose.yml and docker-compose.yaml are the same file under two names — Docker Compose picks up either, and the NAS deployment runs the .yaml. If you fork RoboCo and change a service, keep all three in sync.

Which one to run

For a server you don't intend to hack on, run the registry file — it pulls finished images and needs no source tree or compiler on the host:

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

Two variables choose what you pull (defaults shown):

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

The orchestrator then spawns the matching pre-built agent images on demand (it reads ROBOCO_AGENT_IMAGE_REGISTRY / ROBOCO_AGENT_IMAGE_TAG, which the registry compose wires to the same registry and version). Pin ROBOCO_VERSION to a release tag in production so an upstream latest push can't silently change your fleet.

Build from source only when you're modifying RoboCo:

1docker compose up -d   # builds on first run

The single origin

nginx (docker/nginx.conf, rendered from an envsubst template) is the only externally-exposed service. It listens on localhost:3000 and routes by path:

The browser only ever sees one origin (:3000), so there's no CORS to configure — the panel uses relative /api and /ws URLs and lets nginx dispatch. The panel container is never published directly; you reach it only through nginx. /ws/ also gets a long (86400s) read timeout so live sockets stay open.

The backing services do publish host ports for direct inspection — Postgres on 15432, Redis on 16379, Ollama on 11435, and the orchestrator on 8000. You don't route browser traffic at these; they're there for psql, redis-cli, and the like.

Required host-path mounts

The orchestrator is Docker-in-Docker: it mounts /var/run/docker.sock and spawns agent containers itself. Because those agent bind-mounts resolve on the host daemon (not inside the orchestrator container), several paths must be given as absolute host paths — the orchestrator passes them straight through to docker run -v for each agent.

The host ~/.grok is mounted read-write into the orchestrator (it rewrites the short-lived token in place to keep agents from hanging on an expired login) and read-only into each Grok agent. Run grok login on the host once before enabling Grok. Provider routing and the Grok runtime are covered in the models section.

Data persistence and backup

Everything durable lives under ROBOCO_DATA_DIR (default ./data). On a server, point this at a RAID volume:

1ROBOCO_DATA_DIR=/volume1/roboco/data

For backup, the load-bearing directory is postgres/ (everything that isn't re-derivable). ollama/ and workspaces/ are reconstructible — Ollama re-pulls models, agents re-clone repos — so they're optional in a backup. Take Postgres backups with pg_dump against the published port rather than copying the live data directory:

1pg_dump -h localhost -p 15432 -U roboco roboco > roboco-backup.sql

Secure mode

On a trusted LAN RoboCo runs in header-trust mode by default (ROBOCO_AGENT_AUTH_REQUIRED=false): callers are identified by role headers, no token required. That's the intended homelab setup.

To harden it so one agent can't spoof another's role, turn on fail-closed auth:

1ROBOCO_AGENT_AUTH_REQUIRED=true2ROBOCO_AGENT_AUTH_SECRET=<your HMAC secret>     # already required for docker compose3ROBOCO_PANEL_AGENT_TOKEN=<from make panel-token>

With auth required, every API call must carry a valid X-Agent-Token. The panel runs in your browser and can't hold the signing secret, so nginx injects the CEO's token for it: generate the token with make panel-token (it signs one using your ROBOCO_AGENT_AUTH_SECRET), put it in ROBOCO_PANEL_AGENT_TOKEN, and nginx adds it as X-Agent-Token on /api and /ws. The panel keeps working; the secret never reaches the browser.

ROBOCO_ENCRYPTION_KEY and ROBOCO_AGENT_AUTH_SECRET are both required for any docker compose run — the orchestrator service block guards them with compose :? so the stack refuses to start if either is unset. See Security for the full sandboxing model and the env reference for every knob.

Startup sequence

depends_on conditions enforce a strict boot order; the effective sequence is:

• postgres / redis / ollama must each pass their healthcheck (pg_isready, redis-cli ping, ollama list) before anything downstream starts.
• ollama-init is a one-shot that best-effort pulls the embedding model and the local LLM, then gates success on the models being present — a degraded model registry can't take down a fully-cached deployment.
• orchestrator waits for postgres + redis + ollama healthy, ollama-init completed, and agent-base-image built. On startup it runs the database migrations itself (idempotently, to head) and indexes its knowledge base — you do not run alembic upgrade head by hand for the compose path.
• panel waits for the orchestrator; nginx waits for both.

First boot is the slow one: the model pulls (the LLM is a couple of minutes) plus knowledge-base indexing. Watch it come up:

1docker compose logs -f orchestrator2curl http://localhost:8000/health3docker ps --filter name=roboco

When the orchestrator reports serving, open http://localhost:3000. A boot that hangs is almost always waiting on ollama-init (model pull) or a healthcheck — check docker compose ps to see which service is still starting. Migration and data details are in Data & migrations; recurring boot symptoms are in Common issues.

Operator-relevant Makefile targets

The Makefile drives the host developer workflow (uv-based, for hacking on RoboCo itself) — it is separate from the Docker stack and needs uv on the host. The handful that matter operationally:

Run make help for the full list.

Next

• Environment reference — every ROBOCO_* setting, with defaults and on/off state.
• Data & migrations — the self-migrating schema and what to back up.
• Security — the full agent sandboxing and auth model.