Documentation
Install
Three ways to run yaaf. Pick the one that fits.
| Docker | Native | From source | |
|---|---|---|---|
| For | A server, or any machine you want to run it on for real | Your own Linux desktop or laptop | Working on yaaf itself |
| Runs on | Linux, macOS, Windows (WSL2) | Linux only | Linux, macOS |
| Agents run in | A fresh container per run | A bubblewrap jail per run | A plain process (no isolation) |
| Database | Postgres | SQLite | SQLite |
| Time | A few minutes (about 10 if it builds the images) | ~5 minutes | ~5 minutes |
All three need a model key to do real work: from Anthropic, OpenAI, Google, or any provider yaaf supports. A local Ollama needs no key.
Want to see it work before installing anything? Run a project for $0 with scripted agents:
git clone https://github.com/dominicplouffe/yaaf && cd yaaf
python3 -m venv .venv && .venv/bin/pip install -e . # Python 3.12+
.venv/bin/yaaf rehearse examples/01-your-first-hour.json
Option 1: Docker
You need: Docker with the compose plugin, git, openssl and curl. No
Python or Node; the images carry everything. Linux is the tested path; for a Mac
or Windows, see macOS and Windows first.
1. Install Docker (skip if you have it):
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"
Log out and back in so the group change applies.
2. Install yaaf:
git clone https://github.com/dominicplouffe/yaaf && cd yaaf
deploy/deploy_single_server.sh --admin-email you@example.com
The script creates the secrets, gets both images, starts Postgres, the server and the runner, applies the schema, loads the role library, and makes you the admin. It ends by printing a one-time link to set your password.
It is safe to run again at any time.
3. Open the dashboard. It listens on 127.0.0.1:24247 only, so nothing is
exposed to the network.
-
On this machine: open http://localhost:24247/app.
-
On a remote server: tunnel from your laptop, then open the same address.
ssh -N -L 24247:localhost:24247 you@your-server
Open the setup link, choose a password, and you are in.
Options:
| Flag | Effect |
|---|---|
--admin-email EMAIL |
The first admin’s account |
--port 9090 |
Use another port |
--bind ADDRESS |
Listen on another address. Repeatable. 0.0.0.0 exposes it to every network, so put TLS in front first. |
--skip-roles |
Don’t load the role library |
--build |
Build the images from source instead of pulling them |
To run it on a public server, read DEPLOYMENT.md.
macOS and Windows
Docker works on both through Docker Desktop. These are less tested than Linux; tell us what breaks.
macOS. Install Docker Desktop.
Before the first deploy, keep yaaf’s data in your home folder, which Docker
Desktop shares with containers (/var/lib is not shared):
mkdir -p ~/yaaf-data
echo "YAAF_STATE_ROOT=$HOME/yaaf-data" >> deploy/.env
deploy/deploy_single_server.sh --admin-email you@example.com
Windows. Install WSL2 with Ubuntu, and Docker Desktop with WSL integration turned on for it. Then run every command in this guide inside the Ubuntu terminal, as on Linux.
Native mode needs bubblewrap, which only exists on Linux, so it does not run on either.
Option 2: Native (no Docker)
You need: Linux (Arch, Debian or Ubuntu tested). The installer adds git,
bubblewrap, node, npm and uv if they are missing.
git clone https://github.com/dominicplouffe/yaaf && cd yaaf
deploy/install_desktop.sh
The installer sets up yaaf, then runs yaaf setup, which asks for:
- Your account. An email and a password (12+ characters).
- How to start yaaf. As a background service that starts at login, or a plain background process.
- Your model provider and key. The key is checked before it is saved. Most providers also need a web search key, because most roles browse.
- Desktop extras (optional). App menu entries and notifications.
Then open http://localhost:24247/app.
Run yaaf setup again at any time. It skips what is already done.
Before you choose native mode, know this: each agent runs on your machine,
inside a jail that hides your home folder and yaaf’s keys. But it can use your
network (including local services) and read system files under /usr, /etc
and /opt. If the machine holds anything you would not hand to a stranger’s
script, use Docker.
Ubuntu 23.10 and later blocks bubblewrap by default. yaaf setup stops and
tells you. To allow it, save this as /etc/apparmor.d/bwrap-userns:
abi <abi/4.0>,
include <tunables/global>
profile bwrap-userns /usr/bin/bwrap flags=(unconfined) {
userns,
include if exists <local/bwrap-userns>
}
Then load it and run setup again:
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns
Arch, Fedora and Debian need nothing extra.
Day to day:
| Task | Command |
|---|---|
| Stop | systemctl --user stop yaaf |
| Start | systemctl --user start yaaf |
| Update | yaaf update (backs up the database first) |
| See what an update brings | yaaf update --check |
| Open to your network | yaaf setup --bind <address> |
| Back up | yaaf backup (copy the file off this machine) |
| Health check | yaaf doctor |
Data lives in ~/.yaaf: the database, the master key, workspaces and
artifacts. yaaf backup saves the parts you can’t rebuild into one file;
yaaf restore <file> puts them back.
Option 3: From source
For contributors. Needs Python 3.12+ and Node 20+.
git clone https://github.com/dominicplouffe/yaaf && cd yaaf
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
(cd web && npm install && npm run build)
.venv/bin/yaaf up --no-isolation --email you@example.com
yaaf up creates a master key and a SQLite database in ~/.yaaf, starts the
server and the runner, makes you the admin, loads the role library, and prints
your sign-in link. Ctrl-C stops everything.
--no-isolation means agents run as you, with no sandbox. yaaf will not pick
this for you. For real agents on your machine, use yaaf up --host instead
(needs pip install -e ".[host]" and bubblewrap).
Run the tests:
.venv/bin/pytest -q -n auto
See CONTRIBUTING.md before you open a pull request.
After you install
-
Add a model key. Settings → Providers. Agents cannot run without one. PROVIDERS.md covers every provider, subscriptions and local models.
-
Check the install.
yaaf login yaaf doctordoctorlists anything that is wrong and how to fix it. -
Create a project. In the dashboard, click New Project, or import one of the ready-made specs in
examples/. -
Connect Claude (optional):
yaaf mcp-token mint my-laptop --scopes read claude mcp add --transport http yaaf http://localhost:24247/mcp \ --header "Authorization: Bearer ymt_…"Claude Desktop and Cursor use the same URL and header. claude.ai needs a public address; see DEPLOYMENT.md.
If something goes wrong
| Symptom | Fix |
|---|---|
| Forgot your password | yaaf users setup-link you@example.com (Docker: prefix with docker compose -f deploy/docker-compose.yml exec api) |
Every page errors with relation "projects" does not exist |
The schema is missing. Run docker compose exec api alembic upgrade head from deploy/. |
The api container keeps restarting |
A migration failed. docker compose logs api shows why. |
| No roles to pick when creating a project | The library was not loaded. Re-run deploy/deploy_single_server.sh. |
| A run starts and dies at once | The sandbox image is missing. docker build -f deploy/sandbox/Dockerfile -t yaaf-sandbox:latest . |
| Runs never start | No runner is running. Check docker compose ps, or yaaf doctor. |
| Anything else | yaaf doctor |