Deployment

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.20.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.

Two internal Docker networks, not one

Separate from nginx's browser-facing single origin, all three tracked compose files also split the internal Docker network in two: roboco_default (the agent mesh — panel, nginx, ollama, every spawned agent container, and their sandbox DB/Redis sidecars) and roboco_data (postgres + redis only). The orchestrator is the only multi-homed service, so an agent container cannot resolve or reach roboco-postgres:5432 / roboco-redis:6379 at all — network membership is the entire containment, which matters because Redis has no auth of its own. ROBOCO_DB_NETWORK_ISOLATED (config default false) is set true by these compose files and suppresses the legacy prod-creds gate-env injection accordingly; see DB network isolation.

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. ~/.codex and ~/.gemini are each mounted read-only — Codex's orchestrator-side refresh loop and Gemini's per-container in-process refresh both write only to the image's own local copy, never back to your host credential. ~/.kimi-code is the odd one out: it's mounted read-write and shared into every Kimi agent and the orchestrator, because Moonshot's refresh token rotates with only a short reuse grace — independent per-container copies would eventually cross-invalidate each other, so every container instead redeems the same rotating chain, serialized by the CLI's own cross-process lock. Run codex login / the interactive gemini login / kimi login on the host once before enabling any of the three. Provider routing and the Grok/Codex/Gemini/Kimi runtimes 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

The load-bearing directory is postgres/ (everything else here is either re-derivable or a derived projection of it). ollama/ and workspaces/ are reconstructible — Ollama re-pulls models, agents re-clone repos — so they're not worth backing up at all.

A backup sidecar (pgvector/pgvector:pg16, same image as postgres) ships in both tracked compose files and takes care of Postgres automatically: a pg_dump -Fc on container start and then every 24 hours, written to backups/roboco-<timestamp>.dump, rotated to the newest 14. No flag — it's always on. Setting ROBOCO_BACKUP_MIRROR_DIR to a host path on a different disk additionally mirrors every successful dump there — see Backups for the rotation detail, the off-disk mirror, and the restore procedure (including a quarterly restore-drill script). For a one-off manual dump instead of waiting for the sidecar's cycle, the same command works against the published port:

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

Object storage (MinIO) — default off

MinIO is the optional durable object store for rendered MP4s. Default is off — empty ROBOCO_MINIO_ENDPOINT leaves the existing FileResponse media-serve path byte-for-byte unchanged, so upgrading is a no-op until you opt in. The NAS compose arms it; the registry compose omits it (NAS default-on, registry default-off).

The minio service runs on the data network only (off the agent mesh) with a named minio-data volume; the orchestrator reaches it over its data NIC. Host ports 19000:9000 (API) and 19001:9001 (console) are published for debugging only.

Arming it

Set the five ROBOCO_MINIO_* vars on the orchestrator (see env reference). Once ROBOCO_MINIO_ENDPOINT is non-empty:

• Write path — after each render's local write, the orchestrator PUTs the MP4 to ROBOCO_MINIO_BUCKET keyed by its filename. The PUT is non-fatal: if MinIO is down, the render still succeeds and stays on local disk (the source of truth); the failure is only logged.
• Serve path — the panel preview's media route streams the object from MinIO via StreamingResponse, with _require_ceo auth kept end-to-end (no presigned URLs, no redirect — same URL/headers/body the panel's axios-blob flow already uses). If the object is missing (a render predating MinIO) or MinIO is down, the route falls back to FileResponse from the local render dir.

Backfilling existing renders

Renders created before MinIO was armed live only on the bind mount. Copy them in with mc:

1mc alias set local http://localhost:19000 $ROBOCO_MINIO_ACCESS_KEY $ROBOCO_MINIO_SECRET_KEY2mc cp --recursive ./data/video-renders local/$ROBOCO_MINIO_BUCKET/

The serve route falls back to the local file for any key not yet in the bucket, so backfill is safe to run while the panel is up.

Pointing a dev env at MinIO

A dev (non-NAS) environment can target the NAS MinIO by setting the five ROBOCO_MINIO_* vars to the NAS endpoint (and ensuring the dev host can reach roboco-minio / the published port). For a fully local dev MinIO, run the minio image standalone and point ROBOCO_MINIO_ENDPOINT at it; minio-init creates the bucket idempotently.

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.

Cloud auth — for exposing the panel beyond the LAN

Header-trust and ROBOCO_AGENT_AUTH_REQUIRED both assume the agent fleet's identity headers. If you want the CEO's own browser session to require a login instead of relying purely on network trust, arm ROBOCO_CLOUD_AUTH_ENABLED — a single seeded user, a sliding 30-day session cookie, and a startup guard that refuses to boot without ROBOCO_CLOUD_AUTH_SECRET set.

1ROBOCO_CLOUD_AUTH_ENABLED=true2ROBOCO_CLOUD_AUTH_EMAIL=you@example.com3ROBOCO_CLOUD_AUTH_PASSWORD=<a strong password>4ROBOCO_CLOUD_AUTH_SECRET=<from: python -c 'import secrets; print(secrets.token_hex(32))'>

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.

Makefile enforcement for agents

The agent runtime uses the same Makefile discipline as the host developer workflow. When an agent is working in a repository that has a Makefile, the bash guard routes quality commands through make targets and blocks the raw package-manager invocations that would bypass the project's guards.

• Agents run make quality, make gate, make lint, or make test instead of calling uv run ..., pip install ..., conda ..., or poetry ... directly.
• The bash guard rejects raw uv run, pip install, conda, and poetry invocations whenever a Makefile is present in the working directory.
• This preserves the Makefile's UV_NO_SYNC=1 setting and its private UV_CACHE_DIR, preventing the concurrent-venv-corruption race that bare uv run would trigger.

This applies to the agent's runtime path inside a task branch, not to the NAS operator commands you run by hand. For the host operator workflow, the targets in the table above still behave the same way.

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.
• Cloud auth and DB network isolation — the two settings on this page that change trust boundaries rather than add a background job.

llms.txt