04 β Configure & run
Start CoStaff
Bring the full stack up with one command. First run builds images; later runs reuse the cache.
costaff start
Preflight check
Before touching Docker, costaff start validates your .env: the model API key, the database URI, the security secrets, and the workspace directory. Anything fatal (e.g. no GOOGLE_API_KEY) aborts the start with the exact fix β instead of letting a container crash-loop. Skip it with --no-preflight if you know what you're doing.
What happens
Layered start, in this order:
- Postgres β bundled
postgres:15container holding sessions, project tasks, and identity tables. - Registered agents β each agent's A2A endpoint + MCP server come up.
- Manager Agent β the orchestrator, on port
18080. - Channels β WebChat, Telegram, etc.
The first run also builds the Docker images, which takes a few minutes. Later starts hit the build cache and finish in seconds.
Other lifecycle commands
| Command | What it does |
|---|---|
costaff start | Layered up. Builds images if missing. |
costaff start --no-build | Start without rebuilding β fast. |
costaff start --no-preflight | Skip the .env preflight validation. |
costaff stop | Stop all containers; volumes retained. |
costaff restart | Stop, then start. Equivalent to stop + start. |
Default ports
| Service | Host port |
|---|---|
| Manager Agent | 18080 |
| Channels (WebChat, β¦) | 18090β18099, auto-assigned in add order β costaff channel list shows each channel's port |
| Specialist agents (A2A health) | 18100β18199, auto-assigned, bound to 127.0.0.1 only |
| Postgres | 5432 |
Override COSTAFF_AGENT_PORT in ~/.costaff/costaff/.env if the Manager port conflicts with something on your host.