Rehearse for $0

Documentation

Deployment

docs/DEPLOYMENT.md ↗

How yaaf runs on a server, and how to keep it running. To install it the first time, start with INSTALL.md.

The shape

One server, Docker Compose, four containers:

Container What it does
db Postgres 16. Holds all state.
api yaaf-server: the API, the dashboard, the dispatcher and janitor.
runner yaaf-runner: starts one sandbox container per agent run.
sandboxes Short-lived containers from the yaaf-sandbox image, one per run.

Optional, via compose profiles: minio (S3 storage for artifacts, --profile s3) and public (a locked-down listener for claude.ai, --profile public).

One server is the intended setup, not a starter kit. Agents spend their time waiting on model providers, so you hit provider rate limits long before you run out of server. Need more? Add runners (see Scaling).

Server size: each agent run gets up to 2 CPUs and about 2 GB. Size the box for the number of runs your projects allow at once (each project’s concurrency cap is a setting).

What the deploy script does

deploy/deploy_single_server.sh runs these steps. Each one is safe to repeat.

  1. Checks Docker, openssl and curl are present.
  2. Creates folders at /var/lib/yaaf/workspaces and /var/lib/yaaf/artifacts.
  3. Creates deploy/.env with a new YAAF_MASTER_KEY. Never overwrites it.
  4. Binds the port to 127.0.0.1:24247 (in deploy/docker-compose.override.yml).
  5. Gets two images: the app (deploy/Dockerfile) and the sandbox (deploy/sandbox/Dockerfile). See Images.
  6. Starts the stack. Migrations run when the containers start.
  7. Checks the schema reached the latest migration.
  8. Creates the first admin if there is none, and prints a setup link.
  9. Loads the role library and ready-made teams. Adds only what is missing.

Images

CI publishes both images for every commit on main, for Intel and ARM (Apple Silicon included):

Image What it is
ghcr.io/dominicplouffe/yaaf The app: api and runner
ghcr.io/dominicplouffe/yaaf-sandbox What each agent run executes inside

Each is tagged sha-<commit>. The deploy and update scripts pull the pair built from exactly the commit you have checked out, so the code that runs is the code you have. They build from source instead when:

  • the checkout has local changes,
  • the commit was never published (a branch, or CI hasn’t finished), or
  • you pass --build.

Releases also get :<version> and :latest, and main gets :main. To use your own registry (for a fork), set YAAF_IMAGE_REGISTRY, for example ghcr.io/you.

Reaching the dashboard

By default yaaf listens on 127.0.0.1 only. Nothing is exposed, so there is nothing to firewall. Pick one way in:

Way How When
SSH tunnel ssh -N -L 24247:localhost:24247 you@server Just you. Simplest.
Private network Tailscale or WireGuard, then --bind <that address> You and your team, from anywhere
Reverse proxy with TLS nginx or Caddy in front, YAAF_PUBLIC_BASE_URL set to the https address A public hostname

Two warnings:

  • Docker ignores ufw. A port Docker publishes on 0.0.0.0 is open to the world, whatever ufw status says. Binding to 127.0.0.1 is what keeps it private.
  • Never expose plain HTTP. Passwords and session cookies would cross the network unencrypted. Put TLS in front first.

Connect claude.ai

Claude Code and Claude Desktop connect to http://localhost:24247/mcp with a token, and need nothing here. claude.ai connects from Anthropic’s servers, so it needs a public https address.

1. Set the public address in deploy/.env, then re-run the deploy script:

YAAF_PUBLIC_BASE_URL=https://yaaf.example.com

2. Publish only four paths. Everything else, including the dashboard and /admin, stays private.

Caddy:

yaaf.example.com {
    @public path /mcp /.well-known/oauth-* /oauth/*
    handle @public { reverse_proxy 127.0.0.1:24247 }
    handle { respond 404 }
}

nginx:

server {
    server_name yaaf.example.com;
    listen 443 ssl;

    location = /mcp                  { proxy_pass http://127.0.0.1:24247; }
    location ^~ /.well-known/oauth-  { proxy_pass http://127.0.0.1:24247; }
    location ^~ /oauth/              { proxy_pass http://127.0.0.1:24247; }
    location / { return 404; }
}

Using Tailscale Funnel? docker compose --profile public up -d starts a Caddy listener on 127.0.0.1:8081 with these rules already in place (deploy/public/Caddyfile). Point the funnel at it.

3. Add the connector. In claude.ai: Settings → Connectors → Add custom connector, URL https://yaaf.example.com/mcp. Sign in with your yaaf account and pick the scopes. Start with read.

If the connector can’t register, check YAAF_PUBLIC_BASE_URL first. The server logs the address it advertises at startup.

Updating

deploy/update_single_server.sh

It refuses to run on a checkout with local edits, then: pulls, dumps the database to backups/, gets both images for the new code, restarts, and checks the migrations applied. Migrations need no extra step. That dump is for undoing a bad migration; for real backups, see Backups.

Flag Effect
--no-pull Don’t git pull; update to what is checked out
--build Build the images from source instead of pulling them
--no-backup Skip the backup (not recommended)
--keep-chat Leave running CEO chat sessions on the old code

yaaf is pre-1.0. Read the commit log before you update a server with running projects.

Roll back by restoring the backup the update took:

gunzip -c backups/<file>.sql.gz | docker compose -f deploy/docker-compose.yml exec -T db psql -U yaaf -d yaaf

Native installs update with yaaf update. It backs up the SQLite database to ~/.yaaf/backups, pulls, rebuilds only what changed, and restarts.

Backups

Three things matter, and one command saves all three in a single file:

What Where Why
Database Docker volume pgdata Everything yaaf knows
Master key deploy/.env Without it, every stored API key is unreadable. It cannot be recovered.
Artifacts /var/lib/yaaf/artifacts Files your agents produced
deploy/backup_single_server.sh

It writes backups/yaaf-backup-<date>.tar.gz, readable by you only. The file holds your master key: store it like a password, and copy it off the server. A backup on the same disk doesn’t survive the disk.

Flag Effect
--out PATH Write it somewhere else, like a mounted backup drive
--workspaces Also include the agents’ working folders

To run it nightly, add a cron line (crontab -e) that runs the script with --out pointing at your backup drive.

Restore a backup. It saves the current database, deploy/.env and artifacts first, then restores and restarts yaaf:

deploy/restore_single_server.sh backups/yaaf-backup-<date>.tar.gz

Native installs use yaaf backup and yaaf restore <file>. Same contents, from ~/.yaaf.

Stopping

deploy/kill_single_server.sh

Stops everything and keeps all data. Run the deploy script to bring it back.

Flag Effect
--wipe Deletes the database. Asks you to type DESTROY first.
--sandboxes Only clean up leftover sandbox containers
--keep-sandboxes Stop, but leave sandbox containers alone

Health

  • GET /healthz: the process is alive.
  • GET /readyz: the database is reachable and the schema exists. Returns 503 if not. Point your monitoring here.
  • yaaf doctor: checks the whole install and says what to fix.
  • yaaf smoke <credential>: one real, tiny call per model key, to prove the key and network path work.
  • Logs: docker compose -f deploy/docker-compose.yml logs -f api runner.

Network

Agents need outbound HTTPS to the model providers you use. The server needs it too (for key checks and the Founder), plus:

  • raw.githubusercontent.com for the model price feed. Without it, turn upkeep off (yaaf upkeep --disable) and import prices by hand.
  • oauth2.googleapis.com if you use Vertex AI.

Sandboxes have open outbound network access. A local model server (Ollama, LM Studio, vLLM) must join the sandbox network (YAAF_SANDBOX_NETWORK), and its address is its container name, like http://ollama:11434/v1, not localhost.

Scaling

Add runners, not servers. Runs are leased from the database, so several runners on several machines can share one database safely. Each runner needs:

  • the same YAAF_DATABASE_URL and YAAF_MASTER_KEY
  • its own YAAF_WORKER_NAME
  • Docker, with the sandbox image (pulled or built)

Two stacks on one server

To run a staging copy beside production, set these four in the second stack’s deploy/.env, and use another port (--port 8081):

YAAF_STACK=staging
YAAF_STATE_ROOT=/var/lib/yaaf-staging
YAAF_SANDBOX_NETWORK=yaaf_sandbox_staging
YAAF_SANDBOX_IMAGE=yaaf-sandbox:staging

Skip any one and the two stacks share containers, files, a network or code. See CONFIGURATION.md.

Doing it by hand

The deploy script is the supported path. If you need to see every step:

sudo mkdir -p /var/lib/yaaf/workspaces /var/lib/yaaf/artifacts
echo "YAAF_MASTER_KEY=$(openssl rand -base64 32)" > deploy/.env

cat > deploy/docker-compose.override.yml <<'YML'
services:
  api:
    ports: !override
      - "127.0.0.1:24247:8080"
YML

docker build -f deploy/sandbox/Dockerfile -t yaaf-sandbox:latest .
(cd deploy && docker compose up -d --build)
(cd deploy && docker compose exec -T api alembic current)    # expect "(head)"
(cd deploy && docker compose exec -T api yaaf users bootstrap \
   --email you@example.com --base-url http://localhost:24247)

Then load the role library from a checkout with the CLI installed:

export YAAF_API=http://localhost:24247
yaaf login
yaaf seed-roles roles/ --only-missing
yaaf seed-crews crews/ --only-missing

Notes:

  • The !override tag matters. Without it, compose keeps the original 0.0.0.0 binding as well.
  • docker compose up --build does not build the sandbox image. Build it yourself.
  • docker compose exec api yaaf seed-roles roles/ does nothing: the image has no roles/ folder. Load roles from the checkout, as above.