# Self-Host Starter

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

Source: https://www.agentclash.dev/docs/getting-started/self-host
Markdown export: https://www.agentclash.dev/md/docs/getting-started/self-host

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](https://www.agentclash.dev/md/docs/fleet/self-host-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](https://github.com/agentclash/agentclash/blob/main/CONTRIBUTING.md#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
make setup
make start
make 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
make status                 # ownership, runtime state, and health
make logs                   # follow Docker and host logs together
make logs FOLLOW=0 TAIL=200 # finite snapshot
make restart                # guarded stop followed by a clean start
make 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
cd web
cp .env.local.example .env.local
pnpm install
pnpm 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
./scripts/dev/seed-local-run-fixture.sh
./scripts/dev/curl-create-run.sh
```

> Warning: `seed-local-run-fixture.sh` is **destructive to your local dev database**. It
> `TRUNCATE`s 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](https://www.agentclash.dev/md/docs/fleet/self-host-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

- [Hosted Quickstart](https://www.agentclash.dev/md/docs/getting-started/quickstart)
- [Self-host at scale](https://www.agentclash.dev/md/docs/fleet/self-host-scale)
- [Fleet overview](https://www.agentclash.dev/md/docs/fleet)
- [Architecture Overview](https://www.agentclash.dev/md/docs/architecture/overview)
- [Contributor Setup](https://www.agentclash.dev/md/docs/contributing/setup)
- [Datasets overview](https://www.agentclash.dev/md/docs/guides/datasets-overview)
- [Multi-turn packs](https://www.agentclash.dev/md/docs/challenge-packs/multi-turn)