Skip to main content
This tutorial gets Army of Agents running on your machine, creates the first company, and brings you to the Home screen.

​
Prerequisites

  • Node.js 20.3 or newer
  • pnpm 9 or newer
  • Git
  • Optional: a local agent CLI such as Claude Code or OpenAI Codex if you want Commander or agents to run immediately
You do not need to create a PostgreSQL database for the default local flow. Army of Agents uses embedded PostgreSQL when DATABASE_URL is unset.

​
1. Clone and install

1

Clone the repository

2

Install dependencies

​
2. Start the local instance

For the fastest first run, use the CLI bootstrap:
With no environment overrides, this writes a loopback-only local_trusted configuration, uses embedded PostgreSQL, stores files locally, stores secrets locally in encrypted form, and starts the app. Keep the command running and open the URL it prints. The default URL is:
If you already configured the instance earlier, restart it with:

​
3. Complete founder onboarding

A new user is routed to /onboarding. The flow resumes at the first incomplete step, so it is safe to refresh the browser or fix a failed check and continue.
1

Create your human profile

Enter your name, title, and timezone. This becomes the initial operator identity.
2

Name the company

Create the first company workspace. One Army of Agents instance can contain multiple companies.
3

Choose the company root folder

Pick an absolute folder path and let Army of Agents verify write access.
4

Configure Commander

Choose a supported Commander runtime and complete the local CLI verification if you want Commander available immediately.
5

Create the first department

Add a department and choose its workspace folder.
6

Create the first agent

Add an agent, select an adapter, and assign it to the department.
7

Review and finish

Confirm the setup summary and enter the product.

​
4. Verify the app is healthy

In another terminal, run:
The health endpoint should return a successful response from the API. The companies endpoint should show the company you created after onboarding.

​
Local development command

If you want the normal developer process instead of the one-command bootstrap, run:
This starts the API and UI at http://localhost:3100. When Google OAuth credentials are absent, the loopback development identity is enabled for local use.
Do not expose the local development identity to a network. Authenticated or public deployments must configure real authentication.

​
Environment overrides

The quickstart respects inherited environment variables. Review your shell before using --yes if you have set values such as:
  • AOA_DEPLOYMENT_MODE
  • HOST
  • DATABASE_URL
  • AOA_PUBLIC_URL
  • storage or secrets variables

​
Troubleshooting

Install pnpm 9 or newer, then re-run pnpm install.
Stop the other process or set a different host or port configuration before starting Army of Agents.
Stop the app, remove the default local database folder, and start again: rm -rf ~/.aoa/instances/default/db && pnpm dev.
Confirm the selected local CLI is installed and authenticated outside Army of Agents, then retry the verification step.

​
Next steps

First agent run

Create a task, wake an agent, and inspect the result.

Core concepts

Learn the vocabulary behind Companies, Team, Commander, Crew, Tasks, Discussions, and Memory.