Getting started.

Prerequisites

• Python 3.13 — the backend runs on 3.13 async features.
• Node 20+ and npm — the PWA is Next.js 16 / React 19.
• Docker — the backend uses a docker-compose file to boot PostgreSQL 16 (with pgvector) and Redis 7.
• An Anthropic API key if you want the LLM tools to actually run. Ollama fallback is wired in for offline dev.

1. Clone the monorepo

git clone https://github.com/agntdot/agnt.git
cd agnt

2. Boot the backend

Copy the example env file, boot Postgres and Redis via docker-compose, run Alembic to the head revision, then start uvicorn.

cd agnt-backend
cp .env.example .env
# Fill in JWT_SECRET, A2A_SIGNING_KEY, HMAC_PHONE_KEY, ENCRYPTION_KEY,
# INTERNAL_API_TOKEN, META_APP_SECRET, TELEGRAM_WEBHOOK_SECRET,
# STRIPE_WEBHOOK_SECRET at minimum.

docker compose up -d            # PostgreSQL 16 + Redis 7
alembic upgrade head            # Run every migration
uvicorn app.main:app --reload --port 8000

3. Boot the PWA

cd agnt-pwa
cp .env.local.example .env.local
# Set NEXT_PUBLIC_API_BASE=http://localhost:8000

npm install
npm run dev                     # http://localhost:3000

4. Run the tests

The backend ships with ~84 tests across four suites. Run them from agnt-backend/:

python -m pytest tests/ -v

# Or by suite:
python -m pytest tests/test_wave1_wave4_hardening.py -v   # 29 hardening tests
python -m pytest tests/test_dupe_search.py -v              # 23 dupe search tests
python -m pytest tests/test_calorie_scan.py -v             # 18 calorie scan tests
python -m pytest tests/test_transport.py -v                # 14 transport tests

The PWA side runs a clean Next.js build as its smoke test:

cd agnt-pwa && npm run build

5. Verify the stack

Two quick health checks to prove the stack is up:

# Backend health (includes ClawPulse circuit breaker state)
curl http://localhost:8000/health

# PWA is serving
curl -I http://localhost:3000/landing

Troubleshooting

Port conflicts

The backend binds :8000, the PWA binds :3000, Postgres binds :5432, and Redis binds :6379. If any of those are in use, either stop the conflicting process or change the ports in docker-compose.yml / your .env.

Alembic head isn't moving

If alembic upgrade headsays there's nothing to do but you know migrations exist, check alembic/versions/ for the latest file number and run alembic current to see where you are. Sequential numbering means missed migrations usually surface as a broken chain.

ClawPulse is disabled

If CLAWPULSE_API_KEYis empty, the gateway registers no agents and all A2A sends return empty dicts (fail-closed). This is fine for local dev where you don't need venue agents — the personal agent path still works end to end.