Local Development

This is the setup for hacking on Agentcy itself or running a fully local instance with hot reload. For day-to-day usage on your laptop, prefer the Desktop App or Docker Compose.

Architecture

Dev mode runs the frontend and backend from source against dockerized data services. Both processes live-reload on file changes.

Prerequisites

• Rust 1.83+ (rustup install stable)
• Node.js 20+ and npm
• Docker Desktop (for Postgres, Neo4j, Redis)
• An LLM API key (Anthropic or OpenAI)

Clone and Bootstrap

Self-hosters get the source via the release tarball or a private repo invite. Once you have it:

cd agentcy
cp .env.example .env
# Edit .env and set LLM_API_KEY

Start Infrastructure

The repo's docker-compose.yml runs Postgres (port 15432), Neo4j (17687), and Redis (16379) — non-default ports so they don't clash with system installs.

docker compose up -d postgres neo4j redis

Run the Backend

The dev-backend.sh script wires up every environment variable for the local stack:

./scripts/dev-backend.sh
# or
make dev-backend

This compiles agentcy-api and runs it on http://localhost:8080. Migrations run automatically on startup.

Run the Frontend

In a second terminal:

cd frontend
npm install
npm run dev

The frontend boots on http://localhost:3000 and points at the local API.

Default Login

The first migration seeds an admin account:

Email:    admin@localhost
Password: admin

Change the password from the UI immediately after first login.

Common Tasks

Reset the database

docker compose down -v   # destroys all volumes
docker compose up -d postgres neo4j redis

Run a specific crate's tests

cargo test -p kg-chat
cargo test -p kg-policy

Build the production binary

cargo build --release -p agentcy-api
# Binary at: target/release/agentcy-api

Frontend type-check and build

cd frontend
npm run type-check
npm run build

Optional Services

OpenFang (sub-agents)

docker compose --profile subagents up -d openfang
export OPENFANG_URL=http://localhost:4200

Grafana (observability)

docker compose --profile grafana up -d grafana
# http://localhost:13000  (admin / admin)

Troubleshooting

Backend won't compile — libsqlite3 errors

Some dev dependencies link against the system SQLite. Install it:

• macOS: brew install sqlite
• Ubuntu: sudo apt-get install libsqlite3-dev

Port already in use

The repo deliberately maps Postgres to 15432, Neo4j Bolt to 17687, and Redis to 16379 to avoid colliding with locally installed services. If those ports are also taken, edit docker-compose.yml and update .env to match.

Migrations fail

Confirm the Postgres container is healthy:

docker compose ps postgres
docker compose logs postgres

If you've changed schemas mid-development, drop the volume (docker compose down -v) and restart.

Next Steps

• Environment Variables — every config knob
• Crate Map — workspace layout and what each crate does
• Docker Compose — same image targets, no source build