Setup Commands - Army of Agents

Instance setup and diagnostics commands.

`aoa run`

One-command bootstrap and start:

pnpm aoa run

Does:

Auto-onboards if config is missing
Runs aoa doctor with repair enabled
Starts the server when checks pass

Choose a specific instance:

pnpm aoa run --instance dev

`aoa onboard`

Interactive first-time setup:

pnpm aoa onboard

First prompt:

Quickstart (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
Advanced setup: full interactive configuration

Start immediately after onboarding:

pnpm aoa onboard --run

Non-interactive defaults + immediate start (opens browser on server listen):

pnpm aoa onboard --yes

`aoa doctor`

Health checks with optional auto-repair:

pnpm aoa doctor
pnpm aoa doctor --repair

Validates:

Server configuration
Database connectivity
Secrets adapter configuration
Storage configuration
Missing key files

`aoa configure`

Update configuration sections:

pnpm aoa configure --section server
pnpm aoa configure --section secrets
pnpm aoa configure --section storage

`aoa env`

Show resolved environment configuration:

pnpm aoa env

`aoa allowed-hostname`

Allow a private hostname for authenticated/private mode:

pnpm aoa allowed-hostname my-tailscale-host

Local Storage Paths

Data	Default Path
Config	`~/.aoa/instances/default/config.json`
Database	`~/.aoa/instances/default/db`
Logs	`~/.aoa/instances/default/logs`
Storage	`~/.aoa/instances/default/data/storage`
Secrets key	`~/.aoa/instances/default/secrets/master.key`

Override with:

AOA_HOME=/custom/home AOA_INSTANCE_ID=dev pnpm aoa run

Or pass --data-dir directly on any command:

pnpm aoa run --data-dir ./tmp/aoa-dev
pnpm aoa doctor --data-dir ./tmp/aoa-dev

`aoa db:backup`

Create a one-off database backup using the current config:

pnpm aoa db:backup

Optional flags:

Flag	Description
`--dir <path>`	Backup output directory (overrides config)
`--retention-days <days>`	Number of days to keep backups before pruning
`--filename-prefix <prefix>`	Filename prefix for the backup file (default: `aoa`)
`--json`	Print backup metadata as JSON

Example — backup to a custom directory and print JSON metadata:

pnpm aoa db:backup --dir /backups/aoa --retention-days 14 --json

The default backup directory is ~/.aoa/instances/default/data/backups. The connection string is resolved from DATABASE_URL env var, then config.database.connectionString, then the embedded-postgres default.

`aoa auth bootstrap-ceo`

Generate a one-time invite URL for the first instance admin (authenticated deployment mode only):

pnpm aoa auth bootstrap-ceo

Optional flags:

Flag	Description
`--force`	Create a new invite even if an admin user already exists
`--expires-hours <hours>`	Invite expiration window in hours (default: 72, max: 720)
`--base-url <url>`	Public base URL used to build the invite link

The command is a no-op in local_trusted deployment mode — it prints an info message and exits. In authenticated mode it revokes any existing un-accepted bootstrap invite before issuing a new one. Example — create an invite that expires in 24 hours:

pnpm aoa auth bootstrap-ceo --expires-hours 24 --base-url https://aoa.example.com

`aoa heartbeat run`

Run one agent heartbeat and stream live logs. Full reference is in Control-plane commands; the essential form is:

pnpm aoa heartbeat run --agent-id <agent-id>

​aoa run

​aoa onboard

​aoa doctor

​aoa configure

​aoa env

​aoa allowed-hostname

​Local Storage Paths

​aoa db:backup

​aoa auth bootstrap-ceo

​aoa heartbeat run