K
Start free

Getting Started

Self-Host Starter

Bring up the local AgentClash stack with the repo’s existing scripts and understand which dependencies are mandatory versus optional.

This is the shortest honest path to a local AgentClash environment today. It is based on the repo’s existing development scripts, not an imagined one-click installer.

Info

For Kubernetes production-shaped installs (Helm, KEDA workers, in-cluster sandboxes, Fleet metrics), see Self-host at scale. This page stays focused on the local developer stack.

Prerequisites

  • Go 1.25+
  • Docker
  • Node.js 22
  • pnpm
  • psql
  • curl

The Temporal CLI is optional. The lifecycle starts Temporal in Docker and uses the host CLI only as a fallback when it is installed.

Info

Just want to look around? The local stack runs with zero external API keys — auth is stubbed, the sandbox provider is a no-op, and a throwaway secrets key is generated at boot. Runs queue but won't execute until you set a sandbox provider key (e.g. E2B_API_KEY) and a model-provider key, and invite emails are logged instead of sent. Everything else works. See Runs with zero API keys in CONTRIBUTING.md for the full picture, including which env vars matter.

1. Start the local stack

From the repo root:

bash
1make setup
2make start
3make status

The lifecycle starts PostgreSQL, Redis, and Temporal through Docker, applies migrations, builds the API server and worker into /tmp/agentclash-local-stack/, and launches those two host processes with recorded ownership. If Docker Temporal cannot become healthy, an installed host Temporal CLI is used and recorded instead.

Use the same interface for the rest of the lifecycle:

bash
1make status                 # ownership, runtime state, and health
2make logs                   # follow Docker and host logs together
3make logs FOLLOW=0 TAIL=200 # finite snapshot
4make restart                # guarded stop followed by a clean start
5make stop                   # stop services but retain containers/data/logs

make doctor remains an alias for make status.

2. Start the web app separately

Next.js uses a different environment-file convention from the Go backend. make setup creates backend/.env; the web copy remains explicit:

bash
1cd web
2cp .env.local.example .env.local
3pnpm install
4pnpm dev

The web app runs at http://localhost:3000. It is not managed by make start, make status, or make stop.

Warning

web/ ships both lockfiles (pnpm-lock.yaml and package-lock.json). Local dev uses pnpm, but CI installs with npm ci against package-lock.json. If you change a frontend dependency, update package-lock.json too or the frontend CI job will fail.

3. Seed a runnable fixture

Back in the repo root:

bash
1./scripts/dev/seed-local-run-fixture.sh
2./scripts/dev/curl-create-run.sh

Warning

seed-local-run-fixture.sh is destructive to your local dev database. It TRUNCATEs the fixture tables (challenge packs, organizations, users, model catalog entries) before inserting deterministic IDs. Only run it against a throwaway local Postgres, never a database with data you care about.

Without a real sandbox provider such as E2B, native runs can still be created, but the model-backed execution path will not complete successfully.

Required vs optional services

  • Managed local stack: PostgreSQL, Redis, Temporal, API server, worker
  • Redis can degrade gracefully in the backend, but the standard contributor lifecycle starts and reports it with the other four services
  • Optional: E2B for sandboxed native execution
  • Optional: S3-compatible storage for production artifact storage

Production notes

Documented production building blocks today include:

  • Railway for the API server and worker (simpler hosted path)
  • Helm chart + KEDA for Kubernetes (Self-host at scale)
  • Temporal Cloud or self-hosted Temporal for orchestration
  • Vercel for web/
  • S3-compatible storage for artifacts
  • E2B or Kubernetes sandboxes for native execution

Verification

The complete managed-stack check is:

bash
make status

You can also hit http://localhost:8080/healthz/ready. Start the separate web server before opening http://localhost:3000.

When finished, run make stop. Stopped Docker containers, named volumes, and logs are retained, so make logs FOLLOW=0 remains useful after shutdown.

See also

PreviousQuickstartNextFirst Eval