Documentation
Configuration
yaaf reads its settings from environment variables that start with YAAF_.
Two kinds of settings, kept apart on purpose:
- Operational (this page): how the install runs. Database, ports, keys, sandboxes, email. Set by whoever runs the server.
- Governed: how a project behaves. Budget, deadline, wake limits, approvals. Stored in the database, per project, and changed in the dashboard. Never in environment variables.
Model API keys are not environment variables. Add them in the dashboard
under Settings → Providers, or with yaaf create-llm-credential. They are
stored encrypted. See PROVIDERS.md.
What you must set
| Install | You set by hand | Recommended |
|---|---|---|
Docker (deploy_single_server.sh) |
Nothing. The script creates YAAF_MASTER_KEY. |
YAAF_PUBLIC_BASE_URL if public, SMTP for email alerts |
Native (yaaf setup) |
Nothing. Setup creates everything in ~/.yaaf. |
SMTP for email alerts |
| Your own setup | YAAF_DATABASE_URL, YAAF_MASTER_KEY, YAAF_SANDBOX_MODE, YAAF_API_BASE_URL |
Everything under Core |
Where to put them
Docker. Put them in deploy/.env, then re-run deploy/deploy_single_server.sh.
Every variable in that file reaches both the api and runner containers.
Containers read settings only when they start.
Native. yaaf setup writes what it needs. To change something, export it
before yaaf up, or edit the service with systemctl --user edit yaaf.
Anywhere else. Export them, or put them in a .env file in the folder you
start yaaf-server and yaaf-runner from.
Core
| Variable | Default | What it does |
|---|---|---|
YAAF_DATABASE_URL |
postgresql+psycopg://yaaf:yaaf@localhost:5432/yaaf |
Where all state lives. Postgres for servers. SQLite works too: sqlite:////path/to/yaaf.db |
YAAF_MASTER_KEY |
(none) | Encrypts every stored secret. Required. Never change it. Back it up. See below. |
YAAF_API_HOST |
127.0.0.1 |
Address the server listens on. The Docker image sets 0.0.0.0 inside the container; the published port decides who can reach it. |
YAAF_API_PORT |
24247 |
Port the server listens on |
YAAF_API_BASE_URL |
http://localhost:24247 |
How the runner and sandboxes reach the server. Change it if you change the port. |
YAAF_PUBLIC_BASE_URL |
(none) | The https address people use, like https://yaaf.example.com. Needed for claude.ai, OAuth data sources, and secure cookies. |
YAAF_MCP_REDIRECT_HOSTS |
claude.ai,claude.com,localhost,127.0.0.1 |
Hosts an MCP client may return to after sign-in. Widen with care. |
The master key
YAAF_MASTER_KEY must be a Fernet key: 32 random bytes, url-safe base64,
with padding. Make one with either:
openssl rand -base64 32
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
Do not use Python’s secrets.token_urlsafe(32). It drops the padding and
fails the first time you save a secret.
- If you lose it, every stored secret is unreadable. There is no recovery.
- If you edit it by hand, the same. To change it, rotate it (below).
- If it is empty, the server refuses to save or read any secret.
Docker keeps it in deploy/.env. Native mode keeps it in ~/.yaaf/master.key.
Keep a copy somewhere safe, away from the machine.
Rotating it. This re-encrypts every stored secret under a new key, all at once. If any value can’t be read, nothing changes.
| Install | Command |
|---|---|
| Docker | deploy/rotate_master_key.sh (backs up, stops yaaf, rotates, updates deploy/.env, starts yaaf) |
| Native | systemctl --user stop yaaf, then yaaf rotate-master-key, then systemctl --user start yaaf |
Keep the old key. Backups taken before the rotation can only be read with it.
The Docker script saves it as deploy/.env.<date>.bak; native mode keeps it
as ~/.yaaf/master.key.<date>.old.
Runner and sandboxes
| Variable | Default | What it does |
|---|---|---|
YAAF_SANDBOX_MODE |
docker |
Where agent runs execute. docker: a container per run. host: a bubblewrap jail on this machine. subprocess: no isolation, development only. |
YAAF_WORKER_NAME |
worker-1 |
This runner’s name. Must be unique when you run several. |
YAAF_SANDBOX_IMAGE |
yaaf-sandbox:latest |
Docker image for agent runs |
YAAF_SANDBOX_NETWORK |
yaaf_sandbox |
Docker network sandboxes join |
YAAF_WORKSPACES_ROOT |
/var/lib/yaaf/workspaces |
Project working folders. In Docker the host path and container path must match. |
YAAF_ARTIFACTS_ROOT |
/var/lib/yaaf/artifacts |
Files agents produce |
YAAF_STACK |
deploy |
Labels the containers this install owns. See second stack. |
YAAF_ALLOW_HOST_SUCCESS_TESTS |
false |
subprocess mode only. Lets agent-written tests run on the host. Keep it off on any real server. |
Native (host) mode only
| Variable | Default | What it does |
|---|---|---|
YAAF_HOST_RUN_CPUS |
2.0 |
CPU cap per run. 0 means no cap. |
YAAF_HOST_RUN_MEMORY_GB |
2.0 |
Memory cap per run, in GB. 0 means no cap. |
YAAF_HOST_JAIL_BINDS |
(empty) | Extra read-only paths a run may see, separated by :. Use it when a CLI like Codex lives in your home folder. yaaf setup fills this for you. |
Email and alerts
Optional. Without them, alerts only go to the logs and the dashboard.
| Variable | Default | What it does |
|---|---|---|
YAAF_SMTP_HOST |
(none) | Mail server. Setting it turns email on. |
YAAF_SMTP_PORT |
587 |
Use 587 (STARTTLS). Port 465 does not work. |
YAAF_SMTP_USERNAME |
(none) | Leave empty for a relay that needs no login |
YAAF_SMTP_PASSWORD |
(none) | For Gmail, an App Password |
YAAF_SMTP_FROM |
the username | Sender address. Must be one your provider lets you send as. |
YAAF_CHAIRMAN_WEBHOOK_URL |
(none) | Any URL that accepts a JSON POST with a text field, like a Slack incoming webhook |
You get alerts for budget pauses, approvals waiting on you, and runs that die.
Artifact storage (S3)
Optional. By default artifacts are files under YAAF_ARTIFACTS_ROOT. To use
S3, MinIO or Cloudflare R2, install pip install 'yaaf[s3]' and set:
| Variable | Default |
|---|---|
YAAF_ARTIFACT_S3_ENDPOINT |
(none; setting it turns S3 on) |
YAAF_ARTIFACT_S3_BUCKET |
yaaf-artifacts |
YAAF_ARTIFACT_S3_ACCESS_KEY |
(none) |
YAAF_ARTIFACT_S3_SECRET_KEY |
(none) |
Set the same values on both the server and the runner.
The bundled MinIO (docker compose --profile s3 up -d) reads
MINIO_ROOT_USER (default yaaf) and MINIO_ROOT_PASSWORD. The deploy script
writes a random password to deploy/.env; there is no default. Its ports
listen on 127.0.0.1 only. Point yaaf at it with
YAAF_ARTIFACT_S3_ENDPOINT=http://minio:9000.
Timing
You rarely need these. All values are seconds.
| Variable | Default | What it does |
|---|---|---|
YAAF_DISPATCH_POLL_S |
2.0 |
How often the dispatcher looks for work |
YAAF_JANITOR_POLL_S |
15.0 |
How often the janitor enforces rules |
YAAF_RUNNER_POLL_S |
2.0 |
How often a runner looks for queued runs |
YAAF_LEASE_HEARTBEAT_S |
20.0 |
How often a running job checks in |
YAAF_LEASE_TTL_S |
90.0 |
How long without a check-in before a run is declared dead |
Running a second stack
To run a staging copy on the same server as production, set all four in the
second stack’s deploy/.env. Leave them unset for a normal install.
| Variable | Default | Why it must differ |
|---|---|---|
YAAF_STACK |
deploy |
Otherwise both stacks share containers and the database volume |
YAAF_STATE_ROOT |
/var/lib/yaaf |
Otherwise both write the same workspaces and artifacts |
YAAF_SANDBOX_NETWORK |
yaaf_sandbox |
Otherwise one stack’s runs can reach the other’s server |
YAAF_SANDBOX_IMAGE |
yaaf-sandbox:latest |
Otherwise building one stack’s image changes the other’s runs |
YAAF_STATE_ROOT is read by the compose file and scripts only. Use the same
YAAF_MASTER_KEY as production if you will restore a production backup.
Deploy scripts
| Variable | What it does |
|---|---|
YAAF_ADMIN_EMAIL |
In deploy/.env: the account to make admin on a fresh install. Same as --admin-email. |
YAAF_ACCEPT_NATIVE |
Set to 1 to skip the native installer’s “are you sure” question |
YAAF_IMAGE_REGISTRY |
Where to pull published images from. Default ghcr.io/dominicplouffe. Set it for a fork that publishes its own. |
MINIO_ROOT_PASSWORD |
Written by the deploy script for the optional MinIO store. See S3. |
Command line (yaaf)
| Variable | Default | What it does |
|---|---|---|
YAAF_API |
http://localhost:24247 |
Which yaaf the CLI talks to |
YAAF_TOKEN |
(none) | A personal token, instead of yaaf login. For scripts. |
YAAF_HOME |
~/.yaaf |
Native mode’s data folder |
YAAF_WEB_DIST |
web/dist |
Where the built dashboard is |
YAAF_TERMINAL |
(auto) | Terminal command for the desktop extras, like foot or kitty |
Set by yaaf, not by you
Inside a sandbox, yaaf sets its own variables for each run (YAAF_RUN_ID,
YAAF_MODEL, YAAF_PROVIDER, YAAF_API_TOKEN and others). Do not set them
yourself.
YAAF_ADMIN_TOKEN is retired. People sign in with accounts. If an old
deploy/.env still has it, delete the line.