Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coretracker/agentswarm/llms.txt

Use this file to discover all available pages before exploring further.

AgentSwarm runs as a Docker-based stack, so the local development environment mirrors production closely. The setup process clones the repository, initialises Docker services (nginx, server, web, Postgres, Redis), builds the agent runtime images, and installs Node.js dependencies — after which a single command starts the full stack with hot reload for both the server and the web app.

​
Prerequisites

Before you begin, make sure the following tools are installed and available on your PATH:

Docker & Docker Compose

Required for the main app stack and all agent runtime containers. Both docker compose (v2) and docker-compose (v1) are supported.

Node.js 20+ and npm

Required for local development, checks, tests, and builds. Install via nodejs.org or a version manager such as nvm.

Python 3

Required when installing npm dependencies locally because native modules such as node-pty may build from source via node-gyp.

Bash

Required by the helper and harness scripts in scripts/harness/ and by agentswarm.sh.

​
Initial Setup

1

Clone the repository

git clone git@github.com:coretracker/agentswarm.git
cd agentswarm
2

Run the harness setup script

The setup script initialises the Docker stack, builds runtime images, creates the local-plans/ and task-workspaces/ folders, and — when the flag below is set — installs all npm dependencies:
HARNESS_INSTALL_NPM_DEPS=1 ./scripts/harness/setup.sh
What happens under the hood:
  • Creates .env from .env.example if the file is missing.
  • Ensures runtime folders (local-plans/, task-workspaces/) exist.
  • Runs ./agentswarm.sh init to build and start the required containers.
  • Runs npm ci --include=dev to install all workspace dependencies (because HARNESS_INSTALL_NPM_DEPS=1 is set).
Install npm dependencies before running check.sh, test.sh, or pr-ready.sh. Those scripts require a populated node_modules/ tree.
If you only need the Docker services and do not plan to run local checks or tests, you can omit the flag:
./scripts/harness/setup.sh
3

Copy the environment file

If the setup script has not already created .env for you, copy the example file manually and review the values:
cp .env.example .env
Key variables to review:
VariableDefaultNotes
PUBLIC_PORT3217Port exposed by the nginx reverse proxy.
DEFAULT_ADMIN_EMAILadmin@agentswarm.localBootstrap admin email (first-boot only).
DEFAULT_ADMIN_PASSWORDsee .env.exampleBootstrap admin password (first-boot only).
DATABASE_URLsee .env.examplePostgres connection string.
REDIS_HOST_PORT6379Host port for the Redis container.
POSTGRES_HOST_PORT5432Host port for the Postgres container.
The bootstrap admin credentials are written from .env.example and are only used when the first admin user is created. Change DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD before exposing the app outside your local machine.
4

Start the development stack

Run the server and web dev processes together with hot reload:
npm run dev
This uses concurrently to run both @agentswarm/server (via tsx watch) and @agentswarm/web (via Next.js dev server) in parallel.Alternatively, start the full Docker stack (including nginx, Postgres, and Redis) and wait for the health check to pass:
./scripts/harness/start.sh

​
Running Services Individually

You can start the server or web app in isolation using npm workspace commands: 
# Start only the Fastify server with hot reload (tsx watch)
npm run dev -w @agentswarm/server

# Start only the Next.js web app with hot reload
npm run dev -w @agentswarm/web
This is useful when you’re working on one layer and want faster feedback without the overhead of the other process.

​
Verifying the Setup

Once the stack is running, confirm that everything is healthy: 
curl -fsS http://localhost:3217/api/health
A successful response looks like: 
{ "ok": true }
Then open the login page in your browser: 
http://localhost:3217/login
Sign in with the bootstrap credentials from your .env file (defaults from .env.example are admin@agentswarm.local and the password defined there).
After signing in, go to Settings and add your provider credentials for OpenAI/Codex and Anthropic/Claude. Then go to Repositories and add a Git repository before creating your first task.

​
Database Reset

If your local data becomes stale or inconsistent — for example after switching branches or if bootstrap credentials are no longer working — you can wipe and recreate the Postgres and Redis volumes: 
HARNESS_DB_RESET=1 ./scripts/harness/setup.sh
This removes the local Docker volumes for the stack and recreates all services from a clean state. The default admin user will be recreated on the next boot using the values in .env.

​
Doctor Script

The doctor script verifies that all required tools are installed and that the harness scripts are available. Run it first whenever setup fails unexpectedly: 
./scripts/harness/doctor.sh
It checks for docker, docker compose, node, npm, python3, bash, and the presence of the harness scripts themselves. Any missing dependency is reported with a clear message.
If local ports are already in use, override the defaults in .env before running setup:
PUBLIC_PORT=3300 REDIS_HOST_PORT=6380 POSTGRES_HOST_PORT=5433 ./scripts/harness/setup.sh
Or edit the values directly in .env and re-run ./scripts/harness/start.sh.
The node-pty package builds a native module from source using node-gyp, which requires Python 3. If npm ci fails with a message like Could not find any Python installation to use, install Python 3 and retry:
# macOS (using Homebrew)
brew install python3

# Ubuntu / Debian
sudo apt-get install python3

# Then retry
HARNESS_INSTALL_NPM_DEPS=1 ./scripts/harness/setup.sh

Build docs developers (and LLMs) love

Get started for freeTalk to us