maestro/docs/docker.md

English | 日本語

Running MAESTRO with Docker

The fastest way to run MAESTRO is Docker Compose. This guide covers the full path from git clone to a working instance, plus the things that commonly trip people up (Linux networking, the LLM endpoint, data persistence, the sandbox).

TL;DR

Works on Linux and on Windows via WSL2 (Docker Desktop's WSL integration).

docker compose up -d     # builds the image on first run, then starts
# open http://localhost:9876

No .env or config.yaml is required to start: a fresh docker compose up opens a setup wizard in the UI where you point MAESTRO at your LLM. To preset the endpoint instead, cp .env.example .env and set OLLAMA_BASE_URL/OLLAMA_MODEL (see The LLM endpoint).

A fresh container starts with a login. Compose publishes 9876 on all host interfaces, so a Docker host is reachable from your LAN out of the box — and the agent's Bash tool would hand anyone who reaches it code execution. So a new install that binds a non-loopback interface generates an admin account on first boot and prints the password:

$ docker compose logs maestro | grep initial-admin
[initial-admin] ... Sign in as admin@localhost / <generated password> ...

The same password is written to data/.initial-admin-password (mode 0600) in case the log has scrolled away. Sign in, then change it under Settings → Preferences — the reminder stops and the file is removed once you do. The setup wizard lives behind that login, so sign in first and configure the LLM afterwards.

This only happens on a fresh install with no auth section in config.yaml. An existing deployment is never switched to a login behind your back; if it is unauthenticated and reachable, the UI shows a standing warning instead. See Going beyond localhost.

Two consequences worth knowing up front:

• Rebuilding the container keeps the login. config.yaml lives in the image layer, so docker compose up -d --build resets it while /app/data (and your admin account) survives on the named volume. Boot notices the mismatch and turns auth.local back on — your existing password keeps working, nothing is regenerated. Everything else you saved in Settings is still lost on a rebuild: bind-mount config.yaml (writable) or point AAO_CONFIG at a path under the data volume to keep it. To turn the login off deliberately, write auth.local.enabled: false — an explicit setting is never overwritten.
• A read-only config.yaml makes a fresh install refuse to start. It cannot write the auth setting, and coming up unauthenticated on a reachable interface is the one outcome nobody would notice. Make the file writable, configure auth yourself, or bind loopback.
• Wiping the data volume while keeping config.yaml does not lock you out. docker compose down -v leaves a config that says "auth on" with no account behind it; boot notices and mints a fresh admin, printed the same way. If an OAuth provider is configured, it does nothing — you can still sign in there.

Windows (WSL2)

Run the same command inside a WSL2 distro with Docker Desktop's WSL integration enabled — nothing else is needed. The headed-browser stack runs entirely inside the container (no host X server or WSLg), and the repository's .gitattributes keeps the build's shell scripts LF-only, so a Windows checkout (which would otherwise convert them to CRLF) still builds cleanly.

What the container is (and is not)

• It runs the MAESTRO app (web UI, workers, tools, optional gateway).
• It does not run an LLM. You point MAESTRO at an existing OpenAI-compatible endpoint (Ollama, vLLM, a hosted gateway, …).
• The image bundles the headed-browser stack (Xvfb / x11vnc / Chromium) and the Bash sandbox (bubblewrap + a pre-baked Python toolchain), so the Browser tab and sandboxed Bash work out of the box.

The LLM endpoint

.env.example defaults to an Ollama running on the host:

OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
OLLAMA_MODEL=qwen3:32b

host.docker.internal resolves to the host on Docker Desktop (macOS/Windows) and — because docker-compose.yml sets extra_hosts: host.docker.internal:host-gateway — on Linux too. You usually don't need to change anything.

Point it elsewhere when your LLM is not on the Docker host:

# Ollama / vLLM on another machine (use that machine's IP)
OLLAMA_BASE_URL=http://192.0.2.10:11434/v1
# A hosted OpenAI-compatible gateway
OLLAMA_BASE_URL=https://your-gateway.example.com/v1

Make sure the model in OLLAMA_MODEL is actually pulled/served by that endpoint, or task runs will fail at the first LLM call.

Verify it's running

docker compose ps                 # STATUS should become healthy
docker compose logs -f maestro    # watch startup; Ctrl-C to stop following

The container has a healthcheck that polls /health. Once it reports healthy, open http://localhost:9876, create a task, and confirm it progresses. If the LLM endpoint is wrong you'll see connection errors in the logs as soon as a task starts.

Data persistence

Two named volumes survive docker compose down / image rebuilds:

Volume	Mount	Holds
maestro-data	/app/data	SQLite DB, users, skills, secrets
maestro-workspaces	/workspaces	per-task agent workspaces

docker compose down -v deletes these volumes (and all your data) — omit -v to keep them.

Configuration

The image ships a runnable config.yaml (copied from config.yaml.example), and .env overrides the common knobs (LLM endpoint, PORT). For most setups, editing .env is all you need.

To manage the full config.yaml from the host (and have Settings UI edits persist across container recreation), bind-mount it — uncomment in docker-compose.yml:

    volumes:
      - ./config.yaml:/app/config.yaml   # create ./config.yaml first

Create the host file before starting (cp config.yaml.example config.yaml), or Docker will create a directory at that path. Without the bind-mount, Settings UI changes live only inside the container and are lost when it is recreated.

The Bash sandbox in Docker

safety.bash_sandbox defaults to auto: use bubblewrap when available, fall back to a hardened allowlist otherwise. The image installs bubblewrap, so the sandbox is active by default. For multi-user or untrusted workloads set safety.bash_sandbox: always (fail-closed if bubblewrap is unavailable).

bubblewrap needs unprivileged user namespaces. They are enabled on most modern hosts; if your host or container runtime disables them, auto degrades to the hardened allowlist and logs a warning at startup. See operations/bash-sandbox-provisioning.md.

Build vs. prebuilt image

docker compose up builds the image locally from the Dockerfile (there is no published image). The first build downloads Chromium and the Python toolchain, so expect several minutes; later starts reuse the cached image. Rebuild after pulling new code with docker compose up -d --build.

Going beyond localhost

By default Compose publishes 9876 on all interfaces, so the instance is already reachable from your LAN. A fresh install starts with a generated admin login (see Quick start), but that is the floor, not a finished setup. Before you rely on it on any shared or untrusted network, harden it:

1. Change the generated password, or switch to OAuth / your own local accounts.
2. Set safety.bash_sandbox: always.
3. Terminate TLS — either MAESTRO's native HTTPS or a reverse proxy in front.

To keep an instance local-only instead (e.g. reach it over an SSH tunnel), pin the compose port mapping back to 127.0.0.1:9876:9876.

See SECURITY.md and getting-started.md for the full hardening checklist.

Troubleshooting

Symptom	Likely cause
Tasks fail immediately with a connection error	OLLAMA_BASE_URL unreachable from the container, or the model isn't served
host.docker.internal not found (Linux)	extra_hosts removed from compose, or an old Docker without host-gateway — use the host's LAN IP
Settings changes vanish after down/up	config.yaml not bind-mounted (see Configuration)
Browser tab / CAPTCHA pool unstable	/dev/shm too small — compose sets shm_size: 1gb; keep it
All data gone after restart	used docker compose down -v (the -v deletes volumes)