# AgentClash Docs Bundle

Canonical docs home: https://agentclash.dev/docs
Machine-readable index: https://agentclash.dev/llms.txt

This file concatenates the currently shipped AgentClash docs pages into one markdown-oriented bundle for assistants, coding agents, and local retrieval pipelines.

---

# AgentClash Documentation

Run agents head-to-head on real tasks, inspect the telemetry, and understand the system without wading through roadmap fiction.

Source: https://agentclash.dev/docs
Markdown export: https://agentclash.dev/docs-md

AgentClash runs agents against the same task, with the same tools and time budget, then shows you who finished, who stalled, and where the run broke.

These docs are layered for three kinds of readers:

- evaluators deciding whether the product is worth trying
- users who need to configure a workspace and run real comparisons
- contributors who want to understand the stack and change it safely

The current public surface is still early. This docs pass only covers behavior that is already visible in the repo today: the CLI, the local stack, the current run model, and the main runtime components.

Start with the hosted quickstart if you want the shortest path to a real command sequence. Start with self-host if you want the full local stack on your machine. Start with architecture if you are here to hack on the code.

---

# Hosted Quickstart

Validate the CLI against the hosted staging backend, set a workspace, and get to your first runnable command in a few minutes.

Source: https://agentclash.dev/docs/getting-started/quickstart
Markdown export: https://agentclash.dev/docs-md/getting-started/quickstart

This path is for people changing the CLI or trying the product without booting the whole stack locally.

> Note: The hosted quickstart assumes your workspace already has challenge packs and
> deployments. If it does not, stop after `workspace use` and you have still
> verified auth, connectivity, and workspace selection.

## 1. Install the CLI

```bash
npm i -g agentclash
```

## 2. Point the CLI at staging and log in

```bash
export AGENTCLASH_API_URL="https://staging-api.agentclash.dev"
agentclash auth login --device
```

Use `--device` when you are in a remote shell or do not want the CLI to open a browser automatically.

## 3. Pick a workspace

```bash
agentclash workspace list
agentclash workspace use <WORKSPACE_ID>
```

The CLI resolves the API base URL in this order:

```text
--api-url > AGENTCLASH_API_URL > saved user config > http://localhost:8080
```

## 4. Inspect what is already there

```bash
agentclash run list
agentclash run create --help
```

If the workspace is already seeded with challenge packs and agent deployments, create and follow a run:

```bash
agentclash run create --follow
```

## Verification

You should now have:

- a valid CLI login
- a default workspace saved locally
- a working connection to the hosted API
- either a created run or enough context to see what the workspace is missing

## See also

- [Self-Host](https://agentclash.dev/docs-md/getting-started/self-host)
- [Runs and Evals](https://agentclash.dev/docs-md/concepts/runs-and-evals)
- [CLI Reference](https://agentclash.dev/docs-md/reference/cli)

---

# 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://agentclash.dev/docs/getting-started/self-host
Markdown export: https://agentclash.dev/docs-md/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.

> Warning: The repo does not currently ship a Helm chart or a polished production
> installer. What it does ship is a local stack script plus documented Railway
> deployment building blocks for the backend.

## Prerequisites

- Go `1.25+`
- Docker
- Temporal CLI
- Node.js `20+`
- `pnpm`
- `psql`

## 1. Start the local stack

From the repo root:

```bash
./scripts/dev/start-local-stack.sh
```

This script starts PostgreSQL and Redis, applies migrations, launches the Temporal dev server if needed, then starts the API server and worker. Logs are written under `/tmp/agentclash-local-stack/`.

## 2. Start the web app

```bash
cd web
pnpm install
pnpm dev
```

The web app runs at `http://localhost:3000`.

## 3. Seed a runnable fixture

Back in the repo root:

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

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

- Required: PostgreSQL, Temporal, API server, worker
- Optional: Redis for event fanout and rate limiting
- Optional: E2B for sandboxed native execution
- Optional: S3-compatible storage for production artifact storage

## Production notes

The repo’s documented production building blocks today are:

- Railway for the API server and worker
- Temporal Cloud for orchestration
- Vercel for `web/`
- S3-compatible storage for artifacts

## Verification

You should be able to hit:

```bash
curl http://localhost:8080/healthz
```

Then open `http://localhost:3000`.

## See also

- [Hosted Quickstart](https://agentclash.dev/docs-md/getting-started/quickstart)
- [Architecture Overview](https://agentclash.dev/docs-md/architecture/overview)
- [Contributor Setup](https://agentclash.dev/docs-md/contributing/setup)

---

# First Eval Walkthrough

Use the current seeded local path to create a run, stream events, and inspect ranking output without inventing setup that is not in the repo.

Source: https://agentclash.dev/docs/getting-started/first-eval
Markdown export: https://agentclash.dev/docs-md/getting-started/first-eval

This walkthrough sticks to what the repo already supports today: seed local data, create a run, stream events, and inspect the result.

## 1. Bring up the local stack

From the repo root:

```bash
./scripts/dev/start-local-stack.sh
```

If you want the browser UI too:

```bash
cd web
pnpm install
pnpm dev
```

## 2. Seed a runnable fixture

Back in the repo root:

```bash
./scripts/dev/seed-local-run-fixture.sh
```

That script seeds enough data to create a local run through the API.

## 3. Create the run

You can hit the API directly:

```bash
./scripts/dev/curl-create-run.sh
```

Or, if you are using the CLI against a prepared workspace, create and follow the run there:

```bash
agentclash run create --follow
```

## 4. Inspect the result

Once you have a run ID, inspect its status and ranking:

```bash
agentclash run get <RUN_ID>
agentclash run ranking <RUN_ID>
```

If the web app is running, open the workspace run detail view in the browser and inspect the replay and scorecard surfaces from there.

## What you should see

- a run record created in the workspace
- event streaming during execution when you follow the run
- a ranking view once the backend has enough completed run-agent results to score

> Warning: Without a real sandbox provider such as E2B, the native model-backed path can
> still stall or fail after run creation. That is expected in the unconfigured
> local setup.

## See also

- [Self-Host Starter](https://agentclash.dev/docs-md/getting-started/self-host)
- [Runs and Evals](https://agentclash.dev/docs-md/concepts/runs-and-evals)
- [Architecture Overview](https://agentclash.dev/docs-md/architecture/overview)

---

# Runs and Evals

The product language around runs and evals is easy to blur. The current codebase makes one distinction especially important.

Source: https://agentclash.dev/docs/concepts/runs-and-evals
Markdown export: https://agentclash.dev/docs-md/concepts/runs-and-evals

A **run** is the concrete execution object you create, stream, rank, compare, and inspect in AgentClash today.

In the current user-facing product surface, `run` is the first-class noun:

- `agentclash run create`
- `agentclash run list`
- `agentclash run ranking`
- `agentclash compare gate --baseline <RUN_ID> --candidate <RUN_ID>`

A run is not just one model token stream. It is the container for a scored evaluation attempt inside a workspace, including the challenge pack version, selected agent deployments, lifecycle timestamps, and ranking output.

The word **eval** is broader. People use it to mean “the experiment I am trying to run” or “the graded set of results I care about.” That is reasonable, but if you are reading the code or the CLI, you should anchor on this:

- **Run** = the concrete resource you create and query.
- **Eval** = the broader exercise or outcome you are trying to measure.

There are also places in the codebase that refer to eval sessions, but the main shipped workflow today still revolves around runs and ranked run results. If you keep that in your head, the CLI and API are much easier to follow.

## Practical rule of thumb

Use **run** when you are talking about a real resource ID. Use **eval** when you are talking about the experiment design or the larger testing loop.

## See also

- [Hosted Quickstart](https://agentclash.dev/docs-md/getting-started/quickstart)
- [CLI Reference](https://agentclash.dev/docs-md/reference/cli)

---

# Agents and Deployments

Understand how AgentClash turns a build plus runtime/provider resources into a concrete deployment that can be scheduled into a run.

Source: https://agentclash.dev/docs/concepts/agents-and-deployments
Markdown export: https://agentclash.dev/docs-md/concepts/agents-and-deployments

A deployment is the workspace-scoped runnable target that AgentClash can attach to a run.

## Why a deployment exists at all

AgentClash is stricter than a typical playground because it has to compare like with like. A model name by itself is not enough. The scheduler needs a concrete object that says:

- which build is being run
- which build version is current
- which runtime policy applies
- which provider credentials or model mapping are attached

That concrete object is the deployment.

## The current creation contract

The current API schema for `CreateAgentDeploymentRequest` requires:

- `name`
- `agent_build_id`
- `build_version_id`
- `runtime_profile_id`

It also supports these optional fields:

- `provider_account_id`
- `model_alias_id`
- `deployment_config`

The OpenAPI description also says only ready build versions can be deployed.

```mermaid
flowchart LR
  AB[Agent build] --> BV[Ready build version]
  RP[Runtime profile] --> D[Deployment]
  PA[Provider account] --> D
  MA[Model alias] --> D
  BV --> D
  D --> R[Run]
```

## Runtime profiles are the execution envelope

A runtime profile defines how aggressive or constrained execution should be. In the current API and web types, a runtime profile carries fields like:

- `execution_target`
- `trace_mode`
- `max_iterations`
- `max_tool_calls`
- `step_timeout_seconds`
- `run_timeout_seconds`
- `profile_config`

That last field matters. The native executor reads runtime-profile sandbox overrides from `profile_config`, including things like filesystem roots and `allow_shell` or `allow_network` toggles.

The clean mental model is:

- the challenge pack defines what the workload wants
- the runtime profile defines execution ceilings and local overrides
- the deployment binds those choices to a runnable target

## Provider accounts are how credentials enter the system

A provider account is a workspace resource with:

- `provider_key`
- `name`
- `credential_reference`
- optional `limits_config`

The important detail is how credentials are stored.

If you create a provider account with a raw `api_key`, the infrastructure manager stores that value as a workspace secret and rewrites the credential reference automatically to:

```text
workspace-secret://PROVIDER_<PROVIDER_KEY>_API_KEY
```

So the product already prefers indirection over plaintext credentials on the resource itself.

## Model aliases are not just display sugar

The user question usually comes out as “provider alias” or “model alias.” In the current product surface, the real resource is `model alias`.

A model alias maps a workspace-friendly key to a model catalog entry, and can optionally be tied to a provider account. The current fields are:

- `alias_key`
- `display_name`
- `model_catalog_entry_id`
- optional `provider_account_id`

That gives you a stable name inside the workspace even if the underlying provider model identifier is ugly or if you need multiple account-specific mappings.

## A deployment is where these pieces come together

A good way to think about the chain is:

- agent build version: what logic is being deployed
- runtime profile: how it is allowed to execute
- provider account: which credentials or spend limits back external model calls
- model alias: which model selection the deployment should use consistently
- deployment: the runnable handle used by runs

This is why the docs should not collapse deployment into “selected model.” The object is richer than that.

## What the UI and CLI expose today

The current repo already exposes the resource model across multiple surfaces:

- CLI `deployment create` and `deployment list`
- workspace pages for runtime profiles, provider accounts, model aliases, deployments, secrets, and tools
- run creation UI that asks for challenge pack and deployment selection separately

That separation is deliberate. A run is an execution event. A deployment is reusable infrastructure state.

## What is stable versus still moving

The stable part is the dependency chain and the API surface. The still-moving part is how richly each resource is edited in the UI and how much automation exists around them.

So the right docs posture is:

- document the current fields and flows precisely
- avoid pretending the deployment UX is fully polished
- treat the resource model itself as real and important

## See also

- [Configure Runtime Resources](../guides/configure-runtime-resources)
- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Tools, Network, and Secrets](../concepts/tools-network-and-secrets)
- [CLI Reference](../reference/cli)

---

# Challenge Packs and Inputs

Learn what a challenge pack really is in AgentClash, how the bundle is structured, and how inputs become runnable cases.

Source: https://agentclash.dev/docs/concepts/challenge-packs-and-inputs
Markdown export: https://agentclash.dev/docs-md/concepts/challenge-packs-and-inputs

A challenge pack is a versioned YAML bundle that defines the workload, scoring contract, execution policy, and input sets for a repeatable evaluation.

## What makes it a challenge pack instead of a prompt

A challenge pack is not just a task description. In the current repo, a runnable pack carries enough structure for AgentClash to do four jobs consistently:

- execute the same workload again later
- attach one or more deployments to that workload
- score the result using a versioned evaluation spec
- preserve the relationship between a failed case and the evidence that exposed it

That is why the API does not ask you to start a run with a loose prompt blob. It asks for a `challenge_pack_version_id`.

## The current bundle shape

The parser in `backend/internal/challengepack/bundle.go` expects a YAML bundle with these top-level sections:

- `pack`: human metadata like `slug`, `name`, and `family`
- `version`: the executable version block
- `tools`: optional pack-defined composed tools
- `challenges`: the workload definitions
- `input_sets`: the concrete runnable cases

A pack becomes runnable through its `version` block. That block currently carries the load-bearing execution data:

- `number`: the pack version number
- `execution_mode`: `native` or `prompt_eval`
- `tool_policy`: allowed tool kinds and runtime toggles
- `filesystem`: optional filesystem constraints
- `sandbox`: network, env, package, and template configuration
- `evaluation_spec`: the scoring contract
- `assets`: version-scoped files or artifact references

```mermaid
flowchart TD
  P[pack metadata]
  V[version]
  V --> ES[evaluation_spec]
  V --> SB[sandbox]
  V --> TP[tool_policy]
  V --> AS[version assets]
  C[challenges] --> IS[input_sets]
  IS --> CASES[cases]
  V --> RUN[run execution]
  CASES --> RUN
  ES --> SCORE[scorecards]
```

## Challenge, input set, case, and asset are different things

These terms are easy to blur together. Do not blur them.

- challenge pack: the entire versioned bundle
- challenge: one task definition inside the bundle
- input set: one named collection of runnable cases for that pack version
- case: one concrete workload item tied to a challenge via `challenge_key`
- asset: a file-like dependency declared by key and path, optionally backed by a stored artifact ID

The bundle model in the repo uses `input_sets[].cases[]` as the main execution unit. A case can carry:

- `payload`
- structured `inputs`
- structured `expectations`
- `artifacts`
- case-local `assets`

That makes cases more expressive than a single flat prompt. They can reference files, expected outputs, and evaluator inputs without inventing an ad-hoc schema per benchmark.

## The evaluation spec is part of the pack, not global product config

The current evaluation docs are explicit about this. The scoring contract lives inside the pack version’s manifest. That means the pack defines:

- validator keys and types
- metrics and collectors
- runtime limits
- pricing rows used for cost scoring
- scorecard dimensions and normalization thresholds

This matters because AgentClash needs scorecards to remain auditable. When a run is scored, the product can persist the exact `evaluation_spec_id` that was used. The publish response already returns that ID.

## Execution mode matters

Two execution modes are visible in the current code and examples:

- `prompt_eval`: lighter-weight packs that focus on prompt-style evaluation
- `native`: packs that can carry sandbox, tool, and execution policy for richer runs

You should choose the simpler mode unless the workload really needs a sandbox, files, or tool execution.

## Sandbox, tool policy, and internet access belong to the pack version

This is one of the most important design choices in the repo.

The pack version can say what the evaluator is allowed to do:

- which tool kinds are allowed
- whether shell or network access is enabled
- what network CIDRs are allowed
- which additional packages should exist in the sandbox
- which env vars are injected as literal values

In other words, the pack is not only content. It is also policy.

## Assets and artifact-backed packs

The version block, challenge blocks, and case blocks can all reference assets. Each asset has a `key` and `path`, and may also carry `media_type`, `kind`, or `artifact_id`.

That gives you two useful authoring patterns:

- check small fixtures into the pack and refer to them by path
- attach previously uploaded workspace artifacts and refer to them by `artifact_id`

Validation already checks that asset references are real. If a case or expectation points at an artifact key that was never declared, publish-time validation fails.

## Publish and validate are first-class workflow steps

The API and CLI already expose the authoring loop directly:

- validate with `POST /v1/workspaces/{workspaceID}/challenge-packs/validate`
- publish with `POST /v1/workspaces/{workspaceID}/challenge-packs`
- list packs with `GET /v1/workspaces/{workspaceID}/challenge-packs`
- list published input sets with `GET /v1/workspaces/{workspaceID}/challenge-pack-versions/{versionID}/input-sets`

The CLI mirrors that with:

```bash
agentclash challenge-pack validate <file>
agentclash challenge-pack publish <file>
agentclash challenge-pack list
```

Publish returns more than a pack ID. It returns:

- `challenge_pack_id`
- `challenge_pack_version_id`
- `evaluation_spec_id`
- `input_set_ids`
- optional `bundle_artifact_id`

That tells you the pack bundle is treated as a concrete artifact of record, not just transient YAML.

## How a pack becomes a run

A run binds:

- one `challenge_pack_version_id`
- one or more deployment IDs
- optionally one selected input set

From there the worker resolves the pack manifest, execution policy, assets, and scoring contract into the runtime path.

That is why challenge packs are foundational in AgentClash. They are the unit that makes two runs comparable without hand-waving.

## See also

- [Write a Challenge Pack](../guides/write-a-challenge-pack)
- [Agents and Deployments](../concepts/agents-and-deployments)
- [Tools, Network, and Secrets](../concepts/tools-network-and-secrets)
- [Artifacts](../concepts/artifacts)

---

# Replay and Scorecards

Understand how run events become a readable timeline, a defensible score, and a reusable evidence trail.

Source: https://agentclash.dev/docs/concepts/replay-and-scorecards
Markdown export: https://agentclash.dev/docs-md/concepts/replay-and-scorecards

Replay is the ordered event history of a run. Scorecards are the condensed judgments and summaries built from that evidence.

## Why AgentClash stores both

If you only keep a final score, you lose the explanation. If you only keep raw logs, nobody can compare anything quickly. AgentClash needs both because the product is about arguing from evidence, not from vibes.

The canonical event envelope work in the repo makes that boundary explicit. Execution emits structured events. The frontend and downstream analysis layers can replay those events as a timeline. Scorecards then turn the same evidence into something compact enough to rank, filter, and compare.

## Replay is the source of truth

Think of replay as the forensic record. It answers questions like:

- what happened first
- when the agent called a tool
- when the sandbox or infrastructure layer failed
- when artifacts or outputs were produced
- what the final terminal state was

That is why replay data should be preserved even when the top-line score looks obvious. The run may still teach you something the score alone cannot show.

## Scorecards are the decision layer

A scorecard should make a run legible in seconds. The exact schema will keep evolving, but the purpose is stable:

- summarize whether the run passed, failed, or degraded
- attach the evidence that justifies that judgment
- make comparisons across runs possible without rereading the full trace

```mermaid
flowchart LR
  EV[Canonical events] --> RP[Replay timeline]
  EV --> SC[Scorecard]
  RP --> UI[Run detail view]
  SC --> CMP[Compare and ranking views]
```

## How to use both together

The fastest useful workflow is:

1. start with the scorecard to see whether the run is healthy
2. move to the replay timeline to understand why
3. inspect artifacts when the failure is ambiguous or multi-step
4. compare against another run only after you trust the evidence on each side

That sequence sounds basic, but it prevents a common failure mode: overreacting to a single score change without checking whether the underlying run actually exercised the same path.

## See also

- [Interpret Results](../guides/interpret-results)
- [Evidence Loop](../architecture/evidence-loop)
- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Data Model](../architecture/data-model)

---

# Tools, Network, and Secrets

Learn the difference between workspace tools, pack-defined tools, and engine primitives, and how network and secret handling are constrained.

Source: https://agentclash.dev/docs/concepts/tools-network-and-secrets
Markdown export: https://agentclash.dev/docs-md/concepts/tools-network-and-secrets

AgentClash has more than one “tool” layer. If you do not separate them mentally, the rest of the runtime model gets confusing fast.

## There are three different layers to know

### 1. Workspace tool resources

The workspace API already exposes first-class `tools` resources with fields like:

- `name`
- `tool_kind`
- `capability_key`
- `definition`
- `lifecycle_status`

These are infrastructure resources that live alongside runtime profiles, provider accounts, and model aliases.

### 2. Pack-defined composed tools

Inside a challenge pack, the optional top-level `tools` block lets a pack author define custom tool interfaces that the evaluated agent can see.

Those definitions are pack-local. They are part of the authored benchmark bundle.

### 3. Engine primitives

At the bottom are the built-in executor primitives, like `http_request`. These are the concrete operations the runtime knows how to execute safely.

A pack-defined tool can delegate to a primitive. That is the key distinction.

## Primitive versus composed tool

The current validation code expects composed tools to look roughly like this:

```yaml
tools:
  custom:
    - name: check_inventory
      description: Check inventory by SKU
      parameters:
        type: object
        properties:
          sku:
            type: string
      implementation:
        primitive: http_request
        args:
          method: GET
          url: https://api.example.com/inventory/${sku}
          headers:
            Authorization: Bearer ${secrets.INVENTORY_API_KEY}
```

What this means:

- `check_inventory` is the tool name the agent sees
- `http_request` is the engine primitive that actually runs
- `args` is the templated mapping from tool parameters to primitive inputs

So when people ask “primitive tools vs actual tools,” the clean answer is:

- primitives are built-in executor operations
- composed tools are the author-defined tool contracts that delegate to those primitives
- workspace tool resources are a separate infrastructure surface

## Validation is strict on purpose

The current parser and tests already reject several dangerous or ambiguous cases:

- unknown template placeholders like `${missing}`
- self-referencing tools where a tool delegates to itself
- delegation cycles across composed tools
- invalid JSON-schema parameter definitions
- missing primitive names or missing args blocks

That strictness is good. A benchmark bundle should fail at publish time rather than fail mysteriously at run time.

## Tool kinds are a separate gate from tool names

The sandbox policy also carries `allowed_tool_kinds`. That means the pack can say which broad categories are available, for example:

- `file`
- `shell`
- `network`

This is different from a specific composed-tool name. A pack might define `check_inventory`, but the runtime still checks whether the underlying kind is allowed.

## Internet access is not automatic

The current runtime does not treat network as free ambient capability.

There are at least three control points visible in the repo:

- the sandbox/tool policy starts with network disabled by default
- the pack can enable outbound networking through `sandbox.network_access` and related policy toggles
- the `http_request` primitive validates the target URL and CIDR allowlist before making a request

The current `http_request.py` helper does all of this:

- allows only `http` and `https`
- rejects missing hosts
- resolves DNS and checks resolved addresses
- blocks private, loopback, link-local, reserved, and multicast addresses unless explicitly allowlisted
- enforces request and response body limits
- sanitizes error handling so secret-bearing values do not leak back to the agent

So the current answer to “how can you call the external internet?” is:

- use a tool path that ultimately delegates to a network-capable primitive like `http_request`
- enable network access in the pack/runtime policy
- keep the destination within the permitted network rules

## Secrets live outside the pack

The product already exposes workspace-scoped secrets as a first-class surface.

You can:

- list secret keys
- set a secret value
- delete a secret

The list endpoint intentionally returns metadata only. Secret values never come back out.

The CLI surface is:

```bash
agentclash secret list
agentclash secret set <KEY>
agentclash secret delete <KEY>
```

## Where secret references resolve

There are two distinct secret-reference patterns in the current code:

- `workspace-secret://KEY` for provider credential resolution
- `${secrets.KEY}` inside composed-tool argument templates

These are not interchangeable.

`workspace-secret://KEY` is used when the provider layer resolves account credentials.

`${secrets.KEY}` is used during composed-tool argument substitution. The engine then decides whether the target primitive is allowed to receive secret-bearing args.

## Only hardened primitives can accept `${secrets.*}`

This is a security boundary, not a convenience feature.

The current `primitive_secrets.go` file says only secret-safe primitives may receive `${secrets.*}` substitutions, and today that allowlist intentionally includes only `http_request`.

The reason is straightforward:

- secrets must not end up in argv
- secrets must not land in readable sandbox files
- secrets must not come back in response headers or stderr
- secrets must not be echoed into the agent context accidentally

That is also why sandbox `env_vars` are literal-only. The executor explicitly rejects `${...}` placeholders there, and the code comment tells pack authors to use `http_request` headers instead when remote authentication is needed.

## See also

- [Write a Challenge Pack](../guides/write-a-challenge-pack)
- [Configure Runtime Resources](../guides/configure-runtime-resources)
- [Sandbox Layer](../architecture/sandbox-layer)
- [Artifacts](../concepts/artifacts)

---

# Artifacts

Understand workspace artifacts, pack assets, run evidence files, and how downloads are signed and delivered.

Source: https://agentclash.dev/docs/concepts/artifacts
Markdown export: https://agentclash.dev/docs-md/concepts/artifacts

An artifact is a stored file object that AgentClash can keep at workspace scope, attach to runs, reference from challenge packs, and expose through signed downloads.

## What an artifact is in the current product

The current artifact response shape already tells you the core model:

- `workspace_id`
- optional `run_id`
- optional `run_agent_id`
- `artifact_type`
- optional `content_type`
- optional `size_bytes`
- optional `checksum_sha256`
- `visibility`
- `metadata`
- `created_at`

That means artifacts are not only run outputs. They can exist before a run and be used as reusable workspace context.

## There are two important artifact roles

### 1. Workspace-managed files

The workspace UI and API let you upload arbitrary files to the workspace artifact store.

The current artifacts page describes them as files you can:

- use as context in challenge packs
- attach to runs

That is the right mental model. Upload once, then reuse where it makes sense.

### 2. Run evidence files

Runs and replay events can also point at artifacts. Those become part of the evidence trail for later inspection, scoring, or failure review.

That is why replay and failure-review models carry artifact references. Artifacts are part of the audit trail, not just incidental attachments.

```mermaid
flowchart LR
  WA[Workspace artifact upload] --> CP[Challenge pack assets]
  WA --> R[Run]
  R --> EV[Replay events]
  EV --> FR[Failure review]
  CP --> SCORE[Scoring evidence]
```

## Challenge-pack assets and artifact refs

Challenge packs do not embed giant blobs directly into YAML. They declare assets and then refer to them by key.

The bundle model supports assets at multiple levels:

- `version.assets`
- `challenge.assets`
- `case.assets`

Each asset can carry:

- `key`
- `path`
- `kind`
- `media_type`
- optional `artifact_id`

Then other parts of the pack can reference those declared assets using:

- `artifact_refs`
- `artifact_key`
- expectation sources like `artifact:<key>`

Validation already checks that those references are real. If the key or artifact ID does not resolve, validation fails before publish.

## The published bundle is itself tracked as an artifact

When you publish a challenge pack, the response may include `bundle_artifact_id`.

That is an important detail because it means the authored pack bundle is treated as a stored object of record. The product does not only store parsed rows; it can also retain the published source bundle as an artifact.

## Upload and download flow

The current API surface is:

- `GET /v1/workspaces/{workspaceID}/artifacts`
- `POST /v1/workspaces/{workspaceID}/artifacts`
- `GET /v1/artifacts/{artifactID}/download`
- public content route at `/artifacts/{artifactID}/content`

The upload path is multipart and supports:

- `file`
- `artifact_type`
- optional `run_id`
- optional `run_agent_id`
- optional `metadata`

The download flow is intentionally indirect. The API returns a signed URL and expiry, then the actual file content is served through the public content endpoint. That keeps raw artifact content behind signed access rather than exposing direct permanent object URLs.

## Visibility and metadata matter

Artifacts also carry `visibility` and arbitrary JSON `metadata`.

The current UI uses metadata to recover nicer names like `original_filename`. If no filename metadata exists, it falls back to showing the artifact ID prefix.

That sounds minor, but it is a sign that metadata is a first-class part of the artifact model, not just a debug dump.

## When to use artifacts versus inline YAML data

Use inline bundle data when:

- the value is small
- it belongs directly in the challenge definition
- you want the pack to stay self-contained

Use artifacts when:

- the file is large or binary
- you want reuse across packs or runs
- the same file should be downloadable later
- the evidence trail should preserve it as a named object

## See also

- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Write a Challenge Pack](../guides/write-a-challenge-pack)
- [Evidence Loop](../architecture/evidence-loop)
- [Data Model](../architecture/data-model)

---

# Write a Challenge Pack

Author a challenge-pack bundle in YAML, validate it against the current parser, and publish it into a workspace.

Source: https://agentclash.dev/docs/guides/write-a-challenge-pack
Markdown export: https://agentclash.dev/docs-md/guides/write-a-challenge-pack

Goal: write a pack that the current AgentClash parser, validator, and publish flow will accept.

Prerequisites:

- You have the CLI installed and logged in.
- You selected a workspace with `agentclash workspace use <WORKSPACE_ID>`.
- You know whether the pack should be `prompt_eval` or `native`.

## 1. Start from the current minimum shape

This is the smallest honest starting point based on the current bundle parser and tests:

```yaml
pack:
  slug: support-eval
  name: Support Eval
  family: support

version:
  number: 1
  execution_mode: prompt_eval
  evaluation_spec:
    name: support-v1
    version_number: 1
    judge_mode: deterministic
    validators:
      - key: exact
        type: exact_match
        target: final_output
        expected_from: challenge_input
    scorecard:
      dimensions: [correctness]

challenges:
  - key: ticket-1
    title: Ticket One
    category: support
    difficulty: medium
    instructions: |
      Read the request and produce the final answer.

input_sets:
  - key: default
    name: Default Inputs
    cases:
      - challenge_key: ticket-1
        case_key: sample-1
        inputs:
          - key: prompt
            kind: text
            value: hello
        expectations:
          - key: answer
            kind: text
            source: input:prompt
```

This is not a glamorous pack. It is a good pack skeleton because it matches the current parser shape.

## 2. Add execution policy only when you need it

If the pack is `native`, you can add runtime sections like `tool_policy`, `sandbox`, and `tools`.

Example:

```yaml
version:
  number: 2
  execution_mode: native
  tool_policy:
    allowed_tool_kinds:
      - file
      - shell
      - network
  sandbox:
    network_access: true
    network_allowlist:
      - 203.0.113.0/24
  evaluation_spec:
    name: support-v2
    version_number: 2
    judge_mode: hybrid
    validators:
      - key: exact
        type: exact_match
        target: final_output
        expected_from: challenge_input
    scorecard:
      dimensions: [correctness]

tools:
  custom:
    - name: check_inventory
      description: Check inventory by SKU
      parameters:
        type: object
        properties:
          sku:
            type: string
      implementation:
        primitive: http_request
        args:
          method: GET
          url: https://api.example.com/inventory/${sku}
          headers:
            Authorization: Bearer ${secrets.INVENTORY_API_KEY}
```

Use these sections deliberately.

- `tool_policy` decides what kinds of tools are even available.
- `sandbox.network_access` and `network_allowlist` control outbound networking.
- `tools.custom` defines the tool contract the agent sees.
- `implementation.primitive` picks the executor primitive that actually runs.

## 3. Add assets when inputs should point at files

If the pack needs files, declare them as assets instead of hardcoding mystery paths all over the bundle.

Example:

```yaml
version:
  number: 1
  execution_mode: native
  assets:
    - key: fixtures
      path: fixtures/workspace.zip
      media_type: application/zip
```

You can also back an asset with an uploaded artifact by setting `artifact_id` instead of only relying on a repository path.

Then cases and expectations can refer to those assets by key.

## 4. Validate before you publish

The current CLI command is:

```bash
agentclash challenge-pack validate support-eval.yaml
```

This calls the workspace-scoped validation endpoint and checks the same parser and validation logic the publish path uses.

Typical failures the current code will catch early:

- unknown placeholders like `${missing}`
- invalid CIDR entries in `network_allowlist`
- self-referencing or cyclic composed tools
- invalid tool parameter schemas
- unknown artifact keys or nonexistent stored artifact IDs

## 5. Publish the bundle

Once validation passes:

```bash
agentclash challenge-pack publish support-eval.yaml
```

The publish response returns concrete IDs, including:

- `challenge_pack_id`
- `challenge_pack_version_id`
- `evaluation_spec_id`
- `input_set_ids`
- optional `bundle_artifact_id`

Those IDs matter later because run creation asks for a pack version, not a filename.

## 6. Confirm the workspace can see it

```bash
agentclash challenge-pack list
```

If the pack published cleanly, it should show up in the workspace list with its versions.

## Verification

You should now have:

- a bundle YAML file the current parser accepts
- a successful `validate` result
- a published pack version ID you can use in run creation

## Troubleshooting

### Validation says a tool placeholder is unknown

Your `implementation.args` template is referencing a variable that is not declared by the tool parameter schema or available template context.

### Validation says a tool references itself or forms a cycle

Your composed tool graph is recursive. Break the cycle and delegate to a primitive or a non-cyclic tool chain.

### Validation says an artifact key is missing

You referenced an asset or artifact key in a case or expectation that was never declared in the pack.

### The pack needs internet access

Do not assume that adding `http_request` is enough. You also need the relevant sandbox/network policy in the pack and runtime path.

## See also

- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Tools, Network, and Secrets](../concepts/tools-network-and-secrets)
- [Artifacts](../concepts/artifacts)
- [CLI Reference](../reference/cli)

---

# Configure Runtime Resources

Create secrets, provider accounts, model aliases, runtime profiles, and deployments in the order the current product expects.

Source: https://agentclash.dev/docs/guides/configure-runtime-resources
Markdown export: https://agentclash.dev/docs-md/guides/configure-runtime-resources

Goal: assemble the resource chain that turns a ready build version into a runnable deployment.

Prerequisites:

- You already selected a workspace.
- You already have an `agent_build_id` and a ready `build_version_id`.
- You have the provider credential you intend to use.

## 1. Store provider credentials as workspace secrets

If you already want explicit secret management, set the secret first:

```bash
printf '%s' "$OPENAI_API_KEY" | agentclash secret set OPENAI_API_KEY
agentclash secret list
```

The list endpoint returns metadata only. Secret values are not exposed back to you.

## 2. Inspect the model catalog

Model aliases point at model catalog entries, so fetch the catalog first:

```bash
agentclash infra model-catalog list
agentclash infra model-catalog get <MODEL_CATALOG_ENTRY_ID>
```

This gives you the model entry ID you will use when creating the alias.

## 3. Create a provider account

You have two current patterns.

### Pattern A: reference an existing workspace secret

`provider-account.json`:

```json
{
  "provider_key": "openai",
  "name": "OpenAI Workspace Account",
  "credential_reference": "workspace-secret://OPENAI_API_KEY",
  "limits_config": {
    "rpm": 60
  }
}
```

Create it:

```bash
agentclash infra provider-account create --from-file provider-account.json
```

### Pattern B: pass `api_key` directly on creation

```json
{
  "provider_key": "openai",
  "name": "OpenAI Workspace Account",
  "api_key": "<PASTE_KEY_HERE>"
}
```

The current infrastructure manager does not keep that raw value on the account row. It stores the key as a workspace secret and rewrites the provider account to use a `workspace-secret://...` credential reference automatically.

## 4. Create a runtime profile

A runtime profile controls execution target and limits.

`runtime-profile.json`:

```json
{
  "name": "default-native",
  "execution_target": "native",
  "trace_mode": "full",
  "max_iterations": 24,
  "max_tool_calls": 32,
  "step_timeout_seconds": 120,
  "run_timeout_seconds": 1800,
  "profile_config": {
    "sandbox": {
      "allow_shell": true,
      "allow_network": false
    }
  }
}
```

Create it:

```bash
agentclash infra runtime-profile create --from-file runtime-profile.json
```

## 5. Create a model alias

A model alias gives the workspace a stable handle for one model catalog entry.

`model-alias.json`:

```json
{
  "alias_key": "primary-chat",
  "display_name": "Primary Chat Model",
  "model_catalog_entry_id": "<MODEL_CATALOG_ENTRY_ID>",
  "provider_account_id": "<PROVIDER_ACCOUNT_ID>"
}
```

Create it:

```bash
agentclash infra model-alias create --from-file model-alias.json
```

Use aliases when you want deployment configuration and playgrounds to refer to a stable workspace label instead of a raw provider model identifier.

## 6. Create the deployment

The current deployment create contract requires:

- `name`
- `agent_build_id`
- `build_version_id`
- `runtime_profile_id`

Optional but commonly useful:

- `provider_account_id`
- `model_alias_id`

Fast path with flags:

```bash
agentclash deployment create \
  --name support-bot-staging \
  --agent-build-id <AGENT_BUILD_ID> \
  --build-version-id <BUILD_VERSION_ID> \
  --runtime-profile-id <RUNTIME_PROFILE_ID> \
  --provider-account-id <PROVIDER_ACCOUNT_ID> \
  --model-alias-id <MODEL_ALIAS_ID>
```

JSON-file path if you want the full request shape:

```json
{
  "name": "support-bot-staging",
  "agent_build_id": "<AGENT_BUILD_ID>",
  "build_version_id": "<BUILD_VERSION_ID>",
  "runtime_profile_id": "<RUNTIME_PROFILE_ID>",
  "provider_account_id": "<PROVIDER_ACCOUNT_ID>",
  "model_alias_id": "<MODEL_ALIAS_ID>",
  "deployment_config": {}
}
```

Then:

```bash
agentclash deployment create --from-file deployment.json
```

## 7. List what you created

```bash
agentclash infra runtime-profile list
agentclash infra provider-account list
agentclash infra model-alias list
agentclash deployment list
```

At that point the workspace has a real runnable target the run-creation flow can select.

## Where tools fit

Workspace tools are their own infra resource surface:

```bash
agentclash infra tool list
agentclash infra tool create --from-file tool.json
```

That is separate from pack-defined composed tools. Do not mix those up in your mental model.

## Verification

You should now have:

- a workspace secret for provider credentials
- a provider account that resolves credentials indirectly
- a runtime profile defining execution limits
- a model alias pointing at a model catalog entry
- a deployment that can be selected during run creation

## Troubleshooting

### Deployment creation fails because the build version is not deployable

The current API requires a ready build version. Mark the build version ready before deploying it.

### I do not know which model alias to create

Start from `agentclash infra model-catalog list`, then create the alias only after you know which catalog entry and provider account you want to bind.

### I passed an API key directly and now cannot see it again

That is expected. Raw provider keys are stored as workspace secrets and the account keeps only a credential reference.

## See also

- [Agents and Deployments](../concepts/agents-and-deployments)
- [Tools, Network, and Secrets](../concepts/tools-network-and-secrets)
- [Config Reference](../reference/config)
- [CLI Reference](../reference/cli)

---

# Interpret Results

Read AgentClash run output from top-line score to raw replay evidence without getting lost.

Source: https://agentclash.dev/docs/guides/interpret-results
Markdown export: https://agentclash.dev/docs-md/guides/interpret-results

Goal: turn a finished run or eval into a decision you can defend.

Prerequisites:

- You have a run or eval to inspect.
- You understand the basic difference between a run and an eval.
- You know which challenge pack or workload the result came from.

## Start with the top-line state

Before you read the full timeline, answer three simple questions:

1. Did the run complete, fail, or time out?
2. Which deployment produced the result?
3. Which challenge pack or input set was this run judged against?

If you skip this step, you will mix together infrastructure problems, workload problems, and actual agent regressions.

## Read the score before the trace

The scorecard or summary view is the fastest way to orient yourself. Use it to identify:

- the overall outcome
- the dimension that changed since the last comparable run
- any obvious outlier input or scenario
- whether the run generated enough evidence to trust the outcome

> Info: A score change is only actionable when the underlying workload is comparable.
> Always confirm you are looking at the same deployment class and challenge pack.

## Use the replay timeline to explain the result

Once you know what changed, move to the replay or event timeline.

A useful reading order is:

1. find the first non-trivial event after run start
2. follow tool calls or sandbox transitions in order
3. locate the first irreversible failure or divergence
4. inspect any terminal event that explains why scoring ended where it did

You are looking for the earliest point where the run stopped being healthy. That might be an agent reasoning mistake, but it might just as easily be a sandbox issue, a bad callback, or a missing artifact.

## Separate agent failures from platform failures

This distinction matters for every comparison review.

Treat these as different buckets:

- agent failure: the deployment ran, but the behavior was wrong or weak
- scenario failure: the workload or scoring context exposed a gap or ambiguity
- platform failure: orchestration, sandbox, callback, artifact, or infrastructure issues broke the run

Only the first bucket should drive model or prompt claims directly.

## Compare runs only after you trust each side

When you compare two runs, make sure both have:

- the same or intentionally different deployment target
- the same workload definition
- enough replay evidence to justify the score
- no obvious infrastructure corruption hiding behind the final state

If one side is missing replay evidence or has an incomplete artifact trail, the comparison is weak even if the ranking UI still renders.

## What to do with a useful failure

A good failure is not just something to fix. It is something to preserve.

When a run reveals a real gap:

1. capture the replay and artifacts that make the issue obvious
2. tie the failure back to the scenario or input that exposed it
3. promote it into a repeatable challenge-pack case when the product surface supports it
4. rerun after the fix so the score change is evidence-backed, not anecdotal

That is the core loop behind serious evaluation work.

## Verification

You should now be able to look at one run and answer:

- what failed
- where it failed first
- whether the failure belongs to the agent, workload, or platform
- what evidence you would preserve for future regression testing

## Troubleshooting

### The score changed, but I cannot explain why

Open the replay view and find the first event where the run diverged from the baseline. If you cannot find one, the run may be missing evidence or you may be comparing different workloads.

### The run failed before any meaningful agent work happened

Treat that as a platform or setup issue first. Check orchestration, sandbox configuration, callbacks, and artifacts before concluding the deployment regressed.

### Two runs disagree, but both look messy

Do not force a ranking conclusion. Clean the workload, rerun under the same conditions, and compare again.

## See also

- [Replay and Scorecards](../concepts/replay-and-scorecards)
- [Runs and Evals](../concepts/runs-and-evals)
- [Evidence Loop](../architecture/evidence-loop)
- [First Eval](../getting-started/first-eval)

---

# Use with AI Tools

Feed AgentClash docs into ChatGPT, Codex, Claude Code, and similar tools using llms.txt and markdown exports.

Source: https://agentclash.dev/docs/guides/use-with-ai-tools
Markdown export: https://agentclash.dev/docs-md/guides/use-with-ai-tools

Goal: give an assistant or coding agent enough AgentClash context to answer questions, draft workflows, or transform the docs into internal runbooks.

Prerequisites:

- You can open or paste URLs into the assistant you are using.
- You know whether you want the full docs bundle or just one page.

## Pick the right docs export

AgentClash now exposes three AI-friendly surfaces:

- `/llms.txt`: a compact index of the shipped docs set
- `/llms-full.txt`: one bundled markdown-oriented export of the full docs corpus
- `/docs-md/...`: page-level markdown exports that mirror `/docs/...`

Use them differently:

- use `llms.txt` when the tool needs a map first
- use `llms-full.txt` when you want one-shot context for a larger prompt
- use `/docs-md/...` when you only need one focused page, like quickstart or config

## Fastest workflow in ChatGPT, Codex, or Claude Code

1. Start with `https://agentclash.dev/llms.txt`.
2. If the tool can fetch URLs directly, give it that URL first.
3. If the tool cannot fetch URLs, open the file yourself and paste the contents.
4. Ask the tool which page it needs next.
5. Feed the relevant `/docs-md/...` page or the full bundle, depending on scope.

That keeps the context tight. Do not dump the full bundle into every prompt by default.

## Good prompt patterns

Use prompts that ask the model to stay anchored to the supplied docs. Examples:

```text
Using https://agentclash.dev/llms.txt, tell me which docs pages I should read to self-host AgentClash and understand the worker architecture.
```

```text
Use the markdown from https://agentclash.dev/docs-md/guides/interpret-results and turn it into a short incident-review checklist for my eval team.
```

```text
Use https://agentclash.dev/llms-full.txt as the product docs corpus and answer only from that material: what is the difference between a run, an eval, and a challenge pack?
```

## When to use page-level exports instead of the full bundle

Prefer page-level exports when:

- you are debugging one subsystem
- you want tighter answers with lower token cost
- the assistant tends to over-generalize when given too much context

Prefer the full bundle when:

- you want a holistic onboarding summary
- you are asking for a docs-wide rewrite or glossary
- you are building internal retrieval or indexing pipelines

## Verification

You should now be able to hand any of these URLs to a tool and get grounded answers:

- `https://agentclash.dev/llms.txt`
- `https://agentclash.dev/llms-full.txt`
- `https://agentclash.dev/docs-md/getting-started/quickstart`

## Troubleshooting

### The assistant cannot open URLs

Open the relevant endpoint yourself and paste the content directly.

### The answer is too vague

Use a narrower `/docs-md/...` page instead of the full bundle.

### The answer mixes product claims with guesses

Tell the tool to answer only from the supplied docs export and cite the page title it used.

## See also

- [Quickstart](../getting-started/quickstart)
- [Config Reference](../reference/config)
- [Codebase Tour](../contributing/codebase-tour)

---

# CLI Reference

Commands, flags, and command groups generated from the current Cobra CLI source.

Source: https://agentclash.dev/docs/reference/cli
Markdown export: https://agentclash.dev/docs-md/reference/cli

This page is generated from the Cobra command definitions in `cli/cmd`.

## Global flags

- `--api-url` — API base URL (overrides config)
- `--json` — Output in JSON format
- `--no-color` — Disable color output
- `--output` (`-o`) — Output format: table, json, yaml
- `--quiet` (`-q`) — Suppress non-essential output
- `--verbose` (`-v`) — Enable debug output on stderr
- `--workspace` (`-w`) — Workspace ID (overrides config)
- `--yes` — Skip confirmation prompts

## Command groups

### `artifact`

Upload and download artifacts

#### `download <artifactId>`

Download an artifact

Flags

- `--output` (`-O`) — Output file path (defaults to stdout)

#### `upload <file>`

Upload an artifact

Flags

- `--metadata` — JSON metadata (optional)
- `--run` — Run ID (optional)
- `--run-agent` — Run agent ID (optional)
- `--type` (required) — Artifact type (required)

### `auth`

Manage authentication

#### `login`

Log in to AgentClash

Flags

- `--device` — Print the verification URL instead of opening the browser automatically
- `--force` — Start a new browser login even if existing credentials are valid

#### `logout`

Log out and remove stored credentials

#### `status`

Show current authentication status

#### `tokens`

Manage CLI access tokens

##### `list`

List your CLI tokens

##### `revoke <token-id>`

Revoke a CLI token

### `build`

Manage agent builds

#### `create`

Create a new agent build

Flags

- `--description` — Build description
- `--name` (required) — Build name (required)

#### `get <id>`

Get agent build with version history

#### `list`

List agent builds

#### `version`

Manage agent build versions

##### `create <buildId>`

Create a new draft version

Flags

- `--agent-kind` — Agent kind: llm_agent, workflow_agent, programmatic_agent, multi_agent_system, hosted_external
- `--spec-file` — JSON file with version spec fields

##### `get <versionId>`

Get a build version

##### `ready <versionId>`

Mark a version as ready (immutable, deployable)

##### `update <versionId>`

Update a draft build version

Flags

- `--spec-file` — JSON file with updated version spec fields

##### `validate <versionId>`

Validate a build version

### `challenge-pack`

Manage challenge packs

#### `list`

List challenge packs

#### `publish <file>`

Publish a challenge pack YAML bundle

#### `validate <file>`

Validate a challenge pack YAML bundle

### `compare`

Compare runs and evaluate release gates

#### `gate`

Evaluate a release gate (nonzero exit = regression or missing evidence)

Flags

- `--baseline` (required) — Baseline run ID (required)
- `--candidate` (required) — Candidate run ID (required)

#### `runs`

Compare baseline vs candidate runs

Flags

- `--baseline` (required) — Baseline run ID (required)
- `--baseline-agent` — Baseline run agent ID (optional)
- `--candidate` (required) — Candidate run ID (required)
- `--candidate-agent` — Candidate run agent ID (optional)

### `config`

Manage CLI configuration

#### `get <key>`

Get a config value

#### `list`

List all config values

#### `set <key> <value>`

Set a config value

### `deployment`

Manage agent deployments

#### `create`

Create an agent deployment

Flags

- `--agent-build-id` — Agent build ID
- `--build-version-id` — Agent build version ID
- `--from-file` — JSON file with deployment spec
- `--model-alias-id` — Model alias ID
- `--name` — Deployment name
- `--provider-account-id` — Provider account ID
- `--runtime-profile-id` — Runtime profile ID

#### `list`

List agent deployments

### `infra`

Manage infrastructure resources

#### `model-catalog`

Browse the global model catalog

##### `get <id>`

Get a model catalog entry

##### `list`

List available models

### `init`

Initialize a project with .agentclash.yaml

Flags

- `--org-id` — Organization ID to bind
- `--workspace-id` — Workspace ID to bind

### `org`

Manage organizations

#### `create`

Create a new organization

Flags

- `--name` (required) — Organization name (required)
- `--slug` — Organization slug (optional, auto-generated)

#### `get <id>`

Get organization details

#### `list`

List organizations you belong to

#### `members`

Manage organization members

##### `invite <orgId>`

Invite a member to the organization

Flags

- `--email` (required) — Email address to invite (required)
- `--role` default: `org_member` — Role: org_admin, org_member

##### `list <orgId>`

List organization members

##### `update <membershipId>`

Update an organization membership

Flags

- `--role` — New role: org_admin, org_member
- `--status` — New status: active, suspended, archived

#### `update <id>`

Update an organization

Flags

- `--name` — New organization name
- `--status` — New status (active, archived)

### `playground`

Manage playgrounds, test cases, and experiments

#### `create`

Create a playground

Flags

- `--from-file` — JSON file with playground spec
- `--name` — Playground name

#### `delete <id>`

Delete a playground

#### `experiment`

Manage playground experiments

##### `batch <playgroundId>`

Create experiments in batch (one per model)

Flags

- `--from-file` — JSON file with batch experiment spec

##### `compare`

Compare two experiments

Flags

- `--baseline` (required) — Baseline experiment ID (required)
- `--candidate` (required) — Candidate experiment ID (required)

##### `create <playgroundId>`

Create an experiment

Flags

- `--from-file` — JSON file with experiment spec

##### `get <experimentId>`

Get an experiment

##### `list <playgroundId>`

List experiments

##### `results <experimentId>`

List results for an experiment

#### `get <id>`

Get a playground

#### `list`

List playgrounds

#### `test-case`

Manage playground test cases

##### `create <playgroundId>`

Create a test case

Flags

- `--from-file` — JSON file with test case spec

##### `delete <testCaseId>`

Delete a test case

##### `list <playgroundId>`

List test cases

##### `update <testCaseId>`

Update a test case

Flags

- `--from-file` — JSON file with test case spec

#### `update <id>`

Update a playground

Flags

- `--from-file` — JSON file with playground spec

### `replay`

View execution replays

#### `get <runAgentId>`

Get execution replay steps

Flags

- `--cursor` — Step offset to start from
- `--limit` — Steps per page (1-200)

### `run`

Manage evaluation runs

#### `agents <runId>`

List agents in a run

#### `create`

Create and submit an evaluation run

Flags

- `--challenge-pack-version` — Challenge pack version ID (optional in a TTY; prompted when omitted)
- `--deployments` — Agent deployment IDs (optional in a TTY; prompted when omitted)
- `--follow` — Follow run events after creation
- `--input-set` — Challenge input set ID (optional)
- `--name` — Run name (optional)

#### `events <runId>`

Stream live run events via SSE

#### `get <id>`

Get run details

#### `list`

List runs in the workspace

#### `ranking <runId>`

Get run ranking and composite scores

Flags

- `--sort-by` — Sort by: composite, correctness, reliability, latency, cost

#### `scorecard <runAgentId>`

Get agent scorecard

### `secret`

Manage workspace secrets

#### `delete <key>`

Delete a secret

#### `list`

List workspace secret keys

#### `set <key>`

Create or update a secret

Flags

- `--value` — Secret value (reads from stdin if omitted)

### `version`

Show CLI version information

### `workspace`

Manage workspaces

#### `create`

Create a workspace

Flags

- `--name` (required) — Workspace name (required)
- `--org` — Organization ID (required)
- `--slug` — Workspace slug (optional)

#### `get <id>`

Get workspace details

#### `list`

List workspaces in an organization

Flags

- `--org` — Organization ID (uses default if not set)

#### `members`

Manage workspace members

##### `invite`

Invite a member to the workspace

Flags

- `--email` (required) — Email address to invite (required)
- `--role` default: `workspace_member` — Role: workspace_admin, workspace_member, workspace_viewer

##### `list`

List workspace members

##### `update <membershipId>`

Update a workspace membership

Flags

- `--role` — New role
- `--status` — New status

#### `update <id>`

Update a workspace

Flags

- `--name` — New workspace name
- `--status` — New status (active, archived)

#### `use <id>`

Set the default workspace

## Source pointers

- `cli/cmd/root.go`
- `cli/cmd/auth.go`
- `cli/cmd/workspace.go`
- `cli/cmd/run.go`
- `cli/cmd/compare.go`

---

# Config Reference

Environment variables and config precedence generated from the current source readers.

Source: https://agentclash.dev/docs/reference/config
Markdown export: https://agentclash.dev/docs-md/reference/config

This page is generated from the config readers in the API server, worker, CLI, and the checked-in backend example environment file.

## CLI precedence

- API URL: `--api-url > AGENTCLASH_API_URL > saved user config > http://localhost:8080`
- Workspace: `--workspace > AGENTCLASH_WORKSPACE > project config > user config`
- Output format: `--json > --output > user config > table`

## API Server Environment

| Variable | Default | Description |
| --- | --- | --- |
| `AGENTCLASH_SECRETS_MASTER_KEY` | — | Read by backend/internal/api/config.go. |
| `API_SERVER_BIND_ADDRESS` | `":8080"` | Bind address for the API server process. |
| `APP_ENV` | `"development"` | Select development, staging, or production behavior. |
| `ARTIFACT_MAX_UPLOAD_BYTES` | `100 << 20` | Upper bound for artifact upload size accepted by the API server. |
| `ARTIFACT_SIGNED_URL_TTL_SECONDS` | `5 * time.Minute` | Expiry window for signed artifact URLs returned by the API server. |
| `ARTIFACT_SIGNING_SECRET` | — | Signing secret for artifact URL generation; required outside local filesystem dev mode. |
| `ARTIFACT_STORAGE_BACKEND` | `"filesystem"` | Choose filesystem or S3-compatible artifact storage. |
| `ARTIFACT_STORAGE_BUCKET` | `"agentclash-dev-artifacts"` | Artifact bucket or logical container name. |
| `ARTIFACT_STORAGE_FILESYSTEM_ROOT` | `filepath.Join(os.TempDir(` | Local artifact root when the filesystem backend is in use. |
| `ARTIFACT_STORAGE_S3_ACCESS_KEY_ID` | — | Access key for S3-compatible artifact storage. |
| `ARTIFACT_STORAGE_S3_ENDPOINT` | — | Optional custom endpoint for S3-compatible artifact storage. |
| `ARTIFACT_STORAGE_S3_FORCE_PATH_STYLE` | `true` | Toggle path-style addressing for S3-compatible storage. |
| `ARTIFACT_STORAGE_S3_REGION` | — | Region for S3-compatible artifact storage. |
| `ARTIFACT_STORAGE_S3_SECRET_ACCESS_KEY` | — | Secret key for S3-compatible artifact storage. |
| `AUTH_MODE` | `"dev"` | Select dev headers or WorkOS-backed authentication for the API. |
| `CORS_ALLOWED_ORIGINS` | — | Allowed browser origins for the API in WorkOS mode. |
| `DATABASE_URL` | `"postgres://agentclash:agentclash@localhost:5432/agentclash?sslmode=disable"` | Postgres connection string. |
| `FRONTEND_URL` | — | Public web origin used in emails and CLI auth links. |
| `HOSTED_RUN_CALLBACK_SECRET` | `"agentclash-dev-hosted-callback-secret"` | Shared secret for hosted-run callback authentication. |
| `RESEND_API_KEY` | — | Enable invite email sending through Resend. |
| `RESEND_FROM_EMAIL` | — | Sender address for invite emails. |
| `TEMPORAL_HOST_PORT` | `"localhost:7233"` | Temporal frontend address. |
| `TEMPORAL_NAMESPACE` | `"default"` | Temporal namespace used by the API and worker. |
| `WORKOS_CLIENT_ID` | — | WorkOS client ID used when the API is in workos auth mode. |
| `WORKOS_ISSUER` | — | Optional WorkOS issuer override for JWT validation. |

## Worker Environment

| Variable | Default | Description |
| --- | --- | --- |
| `AGENTCLASH_SECRETS_MASTER_KEY` | — | Read by backend/internal/worker/config.go. |
| `APP_ENV` | `"development"` | Select development, staging, or production behavior. |
| `DATABASE_URL` | `"postgres://agentclash:agentclash@localhost:5432/agentclash?sslmode=disable"` | Postgres connection string. |
| `E2B_API_BASE_URL` | — | Optional E2B API base URL override. |
| `E2B_API_KEY` | — | API key for the E2B sandbox provider. |
| `E2B_REQUEST_TIMEOUT` | `30*time.Second` | Timeout for E2B sandbox API calls. |
| `E2B_TEMPLATE_ID` | — | Template ID for the E2B sandbox provider. |
| `HOSTED_RUN_CALLBACK_BASE_URL` | `"http://localhost:8080"` | Base URL the worker uses when calling hosted-run callback endpoints. |
| `HOSTED_RUN_CALLBACK_SECRET` | `"agentclash-dev-hosted-callback-secret"` | Shared secret for hosted-run callback authentication. |
| `SANDBOX_PROVIDER` | `"unconfigured"` | Choose unconfigured or e2b for native sandbox execution. |
| `TEMPORAL_HOST_PORT` | `"localhost:7233"` | Temporal frontend address. |
| `TEMPORAL_NAMESPACE` | `"default"` | Temporal namespace used by the API and worker. |
| `WORKER_IDENTITY` | `defaultWorkerIdentity(` | Logical worker identity label. |
| `WORKER_SHUTDOWN_TIMEOUT` | `10 * time.Second` | Graceful shutdown timeout for the worker process. |

## CLI Environment

| Variable | Default | Description |
| --- | --- | --- |
| `AGENTCLASH_API_URL` | — | Override the CLI API base URL. |
| `AGENTCLASH_DEV_ORG_MEMBERSHIPS` | — | Inject development org memberships into the CLI dev-auth path. |
| `AGENTCLASH_DEV_USER_ID` | — | Inject a development user ID for CLI dev mode. |
| `AGENTCLASH_DEV_WORKSPACE_MEMBERSHIPS` | — | Inject development workspace memberships into the CLI dev-auth path. |
| `AGENTCLASH_ORG` | — | Override the default organization ID for CLI commands. |
| `AGENTCLASH_TOKEN` | — | Provide a CLI token directly, mainly for CI or automation. |
| `AGENTCLASH_WORKSPACE` | — | Override the default workspace ID for CLI commands. |

## Backend Example Environment

| Variable | Default | Description |
| --- | --- | --- |
| `AGENTCLASH_SECRETS_MASTER_KEY` | — | Present in the backend example environment file. |
| `API_SERVER_BIND_ADDRESS` | `:8080` | Bind address for the API server process. |
| `APP_ENV` | `development` | Select development, staging, or production behavior. |
| `AUTH_MODE` | `dev` | Select dev headers or WorkOS-backed authentication for the API. |
| `DATABASE_URL` | `postgres://agentclash:agentclash@localhost:5432/agentclash?sslmode=disable` | Postgres connection string. |
| `E2B_API_BASE_URL` | — | Optional E2B API base URL override. |
| `E2B_API_KEY` | — | API key for the E2B sandbox provider. |
| `E2B_REQUEST_TIMEOUT` | `30s` | Timeout for E2B sandbox API calls. |
| `E2B_TEMPLATE_ID` | — | Template ID for the E2B sandbox provider. |
| `FRONTEND_URL` | `http://localhost:3000` | Public web origin used in emails and CLI auth links. |
| `HOSTED_RUN_CALLBACK_BASE_URL` | `http://localhost:8080` | Base URL the worker uses when calling hosted-run callback endpoints. |
| `HOSTED_RUN_CALLBACK_SECRET` | `agentclash-dev-hosted-callback-secret` | Shared secret for hosted-run callback authentication. |
| `REDIS_URL` | `redis://localhost:6379` | Enable Redis-backed event fanout and related features. |
| `RESEND_API_KEY` | — | Enable invite email sending through Resend. |
| `RESEND_FROM_EMAIL` | `noreply@agentclash.dev` | Sender address for invite emails. |
| `SANDBOX_PROVIDER` | `unconfigured` | Choose unconfigured or e2b for native sandbox execution. |
| `TEMPORAL_HOST_PORT` | `localhost:7233` | Temporal frontend address. |
| `TEMPORAL_NAMESPACE` | `default` | Temporal namespace used by the API and worker. |
| `WORKER_IDENTITY` | `agentclash-worker-local` | Logical worker identity label. |
| `WORKER_SHUTDOWN_TIMEOUT` | `10s` | Graceful shutdown timeout for the worker process. |
| `WORKOS_CLIENT_ID` | — | WorkOS client ID used when the API is in workos auth mode. |
| `WORKOS_ISSUER` | — | Optional WorkOS issuer override for JWT validation. |

## Source pointers

- `backend/internal/api/config.go`
- `backend/internal/worker/config.go`
- `cli/internal/config/manager.go`
- `backend/.env.example`

---

# Architecture Overview

AgentClash is a monorepo with a small number of load-bearing runtime components. This page names them and explains why they are split this way.

Source: https://agentclash.dev/docs/architecture/overview
Markdown export: https://agentclash.dev/docs-md/architecture/overview

AgentClash has four main runtime surfaces:

- a Next.js web app for the product UI
- a Go API server for REST and WebSocket traffic
- a Go worker that executes run workflows
- a Go CLI that talks to the API directly

## System sketch

```text
browser / CLI
      |
      v
  API server  ----> Postgres
      |
      +----> Redis (optional event fanout)
      |
      v
   Temporal  <----> worker
                    |
                    +----> provider router
                    +----> sandbox provider (optional E2B)
                    +----> artifact storage
```

## Why it is shaped this way

Temporal is the backbone because long-running agent work is exactly the kind of thing that turns into retry, timeout, cancellation, and partial-progress pain if you try to improvise a one-off orchestrator. The API server stays relatively thin: validate the request, load context, enqueue or signal workflow work, and expose the resulting state. The worker owns the expensive and failure-prone part of the system: provider calls, sandboxed execution, event recording, and workflow activities.

That split also keeps the user-facing web app simpler. The web app does not need to own the run engine. It just renders state, telemetry, and management flows on top of the API.

## Runtime components

### Web

The web app lives in `web/` and is a Next.js app using App Router.

### API server

The API server entry point is `backend/cmd/api-server/main.go`. It loads config, opens Postgres and Temporal clients, initializes storage, auth, and managers, then starts the HTTP server.

### Worker

The worker entry point is `backend/cmd/worker/main.go`. It loads config, connects to Postgres and Temporal, wires the provider router and sandbox provider, and runs the Temporal worker loop.

### CLI

The CLI lives in `cli/`. The root Cobra command is defined in `cli/cmd/root.go`, and the user-facing workflows are grouped under `auth`, `workspace`, `run`, and `compare`.

## Optional infrastructure

- Redis enables event publishing and fanout.
- E2B enables sandboxed native execution.
- S3-compatible storage replaces local filesystem artifact storage in production.

## Code pointers

- `backend/cmd/api-server/main.go`
- `backend/cmd/worker/main.go`
- `cli/cmd/root.go`
- `web/src/app`

## See also

- [Self-Host Starter](https://agentclash.dev/docs-md/getting-started/self-host)
- [Contributor Setup](https://agentclash.dev/docs-md/contributing/setup)

---

# Orchestration

The API server accepts the request, but Temporal and the worker are what make long-running run execution survivable.

Source: https://agentclash.dev/docs/architecture/orchestration
Markdown export: https://agentclash.dev/docs-md/architecture/orchestration

AgentClash models long-running execution as workflow work, not as a single API request that tries to stay alive forever.

## The runtime split

```mermaid
flowchart LR
  BrowserOrCLI[Browser or CLI] --> API[API server]
  API --> Temporal[Temporal]
  Temporal --> Worker[Worker]
  Worker --> Providers[Provider router]
  Worker --> Sandbox[Sandbox provider]
  Worker --> Events[Run event recorder]
```

## What the API server does

The API server handles authentication, authorization, request validation, and persistence setup. For run creation, it wires the request into a Temporal workflow starter rather than trying to execute the whole run inline inside the HTTP handler.

That keeps the API server responsive and gives the platform a durable handoff point for work that may outlive the incoming request.

## What the worker does

The worker connects to Temporal, Postgres, the provider router, and the sandbox provider. It owns the expensive part of the system:

- provider calls
- sandbox-backed execution
- event emission
- result persistence

The worker also decides whether sandbox execution is really available. In the current code, `SANDBOX_PROVIDER=unconfigured` is a valid boot mode, which is why local run creation can succeed even when full native execution is not available.

## Why Temporal is load-bearing here

Run execution is exactly the category of problem where retries, timeouts, cancellation, and partial progress stop being “nice to have” as soon as you leave toy demos. Temporal gives AgentClash a durable workflow backbone so the API server can enqueue work, the worker can resume it, and failures can be handled with explicit workflow semantics instead of improvised queue glue.

## Code pointers

- `backend/cmd/api-server/main.go`
- `backend/cmd/worker/main.go`
- `backend/internal/worker`
- `backend/internal/workflow`

## See also

- [Architecture Overview](https://agentclash.dev/docs-md/architecture/overview)
- [Frontend Architecture](https://agentclash.dev/docs-md/architecture/frontend)

---

# Sandbox Layer

Understand why AgentClash isolates execution behind a sandbox provider boundary and how E2B fits today.

Source: https://agentclash.dev/docs/architecture/sandbox-layer
Markdown export: https://agentclash.dev/docs-md/architecture/sandbox-layer

The sandbox layer is the execution boundary between AgentClash orchestration and the environment where an agent actually runs.

## Why the sandbox boundary exists

The workflow engine should decide what to run and when to retry. It should not directly own process isolation, filesystem risk, network policy, or provider-specific runtime setup. Those concerns change at a different rate and carry a different failure model.

That is why the architecture keeps a boundary between orchestration and execution:

- the API decides that a run should exist
- Temporal workflows coordinate the lifecycle
- the worker performs execution work
- the sandbox provider supplies isolation for the runnable target

## Why E2B is the current fit

The current local-development and worker docs show E2B as the concrete provider in use today. That gives AgentClash a managed isolation layer without having to invent a bespoke container orchestration story inside the app itself.

The main benefits are straightforward:

- isolation is handled outside the web and API processes
- runtime setup is explicit and configurable through worker environment
- the provider can be swapped later without rewriting the product model around runs and evidence

```mermaid
flowchart LR
  API[API server] --> WF[Temporal workflow]
  WF --> WK[Worker activity]
  WK --> SB[Sandbox provider]
  SB --> AG[Agent execution]
  AG --> EV[Replay events and artifacts]
```

## What this boundary protects

This is not only about security. It is also about keeping failure domains honest.

When a run fails, you want to know whether the issue belongs to:

- the scheduler
- the worker logic
- the sandbox provider
- the agent itself

A clean sandbox boundary makes that diagnosis easier because provider setup and execution failures do not get mixed into the same code path as API concerns.

## What to read in the code

Start with these files and directories:

- `backend/internal/worker/config.go` for sandbox-related environment surface
- `backend/internal/worker` for worker-side execution behavior
- `docs/worker/local-development.md` for how the local stack expects the provider to be configured

## Why not bake execution directly into the web or API app

Because that would collapse the concerns that need to stay separate. You would tie request handling, orchestration, and risky execution into the same operational surface. That is faster for a demo and worse for a real evaluation platform.

## See also

- [Orchestration](../architecture/orchestration)
- [Evidence Loop](../architecture/evidence-loop)
- [Self-Host](../getting-started/self-host)
- [Config Reference](../reference/config)

---

# Data Model

Learn the core entities behind workspaces, deployments, challenge packs, runs, and evidence in AgentClash.

Source: https://agentclash.dev/docs/architecture/data-model
Markdown export: https://agentclash.dev/docs-md/architecture/data-model

The AgentClash data model exists to answer one question cleanly: what exactly was run, against what workload, and what evidence did it produce?

## The core entities

At a high level, the schema revolves around a small set of concepts:

- workspaces: the ownership boundary for deployments and evaluation assets
- deployments: the runnable agent targets attached to a workspace
- challenge packs: repeatable workloads that define what should be attempted
- runs: concrete execution attempts
- replay events and artifacts: the evidence emitted while a run executes
- scorecards and comparisons: the summarized judgments built from that evidence

```mermaid
flowchart TD
  WS[Workspace]
  WS --> DP[Deployment]
  WS --> CP[Challenge pack]
  DP --> RN[Run]
  CP --> RN
  RN --> EV[Replay events]
  RN --> AR[Artifacts]
  RN --> SC[Scorecards]
```

## Why the model is shaped this way

The schema is not just there to persist app state. It is there to preserve comparability.

If the system cannot answer these relationships clearly, the product falls apart:

- which workspace owned the evaluated deployment
- which workload definition the run used
- which evidence belongs to that run
- which summary or comparison was derived from that evidence

That is why the data model follows the execution model closely instead of hiding it behind generic analytics tables.

## What the schema needs to make cheap

Three classes of queries matter in practice:

- operator queries: what is currently running, stuck, or failing
- reviewer queries: why did this run score the way it did
- comparison queries: did the new deployment improve or regress on the same workload

The current schema diagrams and domain notes in the repo are already organized around that shape. They optimize for traceability first, not just storage convenience.

## Where to start in the repo

The most useful entry points are:

- `docs/database/schema-diagram.md` for the current entity map
- `docs/domains/domains.md` for domain-level language and ownership boundaries
- `backend/internal/api` for the read and write paths that expose those entities

## See also

- [Runs and Evals](../concepts/runs-and-evals)
- [Challenge Packs and Inputs](../concepts/challenge-packs-and-inputs)
- [Replay and Scorecards](../concepts/replay-and-scorecards)
- [Overview](../architecture/overview)

---

# Evidence Loop

See how AgentClash moves from execution events to replay, scorecards, and future evaluation improvement.

Source: https://agentclash.dev/docs/architecture/evidence-loop
Markdown export: https://agentclash.dev/docs-md/architecture/evidence-loop

The evidence loop is the path that turns a finished run into something you can replay, score, compare, and learn from later.

## Why this loop matters

The hardest part of agent evaluation is not running one experiment. It is preserving enough evidence to make the next experiment smarter.

AgentClash leans on a canonical event model so the same execution can feed multiple consumers:

- a live or replayable timeline
- artifacts and logs for detailed inspection
- scorecards for compact judgments
- future workload design when a failure is worth preserving

```mermaid
flowchart LR
  EX[Execution] --> EV[Canonical events]
  EV --> RP[Replay views]
  EV --> AR[Artifacts and logs]
  EV --> SC[Scorecards]
  RP --> RV[Reviewer understanding]
  SC --> CMP[Comparison decisions]
  RV --> CP[Future challenge-pack improvements]
  CMP --> CP
```

## The canonical event envelope is the hinge

The replay docs in the repo make this explicit: if different subsystems emit ad-hoc logs, you cannot build a trustworthy replay or comparison layer on top. The canonical event envelope is the normalization step that keeps evidence portable.

That gives AgentClash a cleaner stack:

- execution code emits structured events
- the UI can render those events as a timeline
- scoring can summarize those events without losing the underlying trail
- later analysis can reuse the same evidence instead of scraping logs again

## Why scorecards should not replace evidence

A scorecard is the summary, not the truth source. Treat it as the decision layer that sits on top of replay and artifacts. When there is disagreement about a result, the replay and artifact trail should still be there to settle it.

That is the practical reason this loop exists. It keeps ranking and triage honest.

## Where to start in the repo

- `docs/replay/canonical-event-envelope.md` for the event model
- `docs/evaluation/challenge-pack-v0.md` for how useful failures become future workloads
- `web/src/app` for the frontend surfaces that consume replay and results

## See also

- [Replay and Scorecards](../concepts/replay-and-scorecards)
- [Interpret Results](../guides/interpret-results)
- [Data Model](../architecture/data-model)
- [First Eval](../getting-started/first-eval)

---

# Frontend Architecture

The Next.js app is doing three jobs at once: public marketing pages, authenticated product surfaces, and now a public docs experience.

Source: https://agentclash.dev/docs/architecture/frontend
Markdown export: https://agentclash.dev/docs-md/architecture/frontend

The web app is not just the dashboard. It currently carries the product landing pages, AuthKit-based auth flows, authenticated workspace routes, the blog, and the docs surface.

## Route split

```mermaid
flowchart TD
  Root[App Router] --> Public[Public pages]
  Root --> Auth[Auth routes]
  Root --> App[Authenticated workspace and org routes]
  Root --> Docs[Docs routes]
```

## Public pages

The landing page, team page, blog, and docs live in the same Next.js app so they can share typography, branding, and deployment infrastructure. The docs implementation deliberately reuses the same MDX stack already used by the blog instead of adding a second docs framework right away.

## Authenticated app routes

The authenticated product surfaces live under workspace and organization routes and are guarded by WorkOS AuthKit. That split matters for docs because the docs surface needs to stay public even when local WorkOS env is not configured.

## Docs-specific decision

The docs route is now treated as public and bypasses the AuthKit middleware path. That keeps `/docs` reachable in local development and in environments where the docs should be browsable without login.

## Why keep docs in the existing app

For this stage of the product, keeping docs inside the current Next.js app is the pragmatic move:

- no second frontend deployment stack
- reuse of existing fonts, theme tokens, and MDX tooling
- one place to link from product pages into docs

If the docs surface later needs versioning, heavy search, or separate publishing workflows, moving to a more specialized framework still stays open.

## Code pointers

- `web/src/app`
- `web/src/middleware.ts`
- `web/src/lib/blog.ts`
- `web/src/lib/docs.ts`

## See also

- [Architecture Overview](https://agentclash.dev/docs-md/architecture/overview)
- [Hosted Quickstart](https://agentclash.dev/docs-md/getting-started/quickstart)

---

# Contributor Setup

Clone the repo, bring up the local stack, and pick the fastest development loop for the part of AgentClash you are changing.

Source: https://agentclash.dev/docs/contributing/setup
Markdown export: https://agentclash.dev/docs-md/contributing/setup

If you are touching backend workflows or the web product, start the full local stack. If you are only changing the CLI, point the CLI at staging and skip the backend entirely.

## Full-stack local development

### 1. Clone the repo and start the stack

```bash
git clone https://github.com/agentclash/agentclash.git
cd agentclash
./scripts/dev/start-local-stack.sh
```

That script starts PostgreSQL, Redis, Temporal, the API server, and the worker.

### 2. Start the web app

```bash
cd web
pnpm install
pnpm dev
```

### 3. Seed local data

```bash
cd ..
./scripts/dev/seed-local-run-fixture.sh
./scripts/dev/curl-create-run.sh
```

## Faster loop for CLI-only work

If you only need the CLI:

```bash
export AGENTCLASH_API_URL="https://staging-api.agentclash.dev"
cd cli
go run . auth login --device
go run . workspace list
go run . workspace use <WORKSPACE_ID>
go run . run list
```

This is the fastest way to change the CLI without also running the API server and worker locally.

## What lives where

- `backend/cmd/api-server` — API entry point
- `backend/cmd/worker` — worker entry point
- `cli/` — Cobra CLI
- `web/` — Next.js app
- `docs/` — existing internal markdown docs and references
- `testing/` — review contracts, test notes, and issue-specific validation docs

## See also

- [Self-Host Starter](https://agentclash.dev/docs-md/getting-started/self-host)
- [Architecture Overview](https://agentclash.dev/docs-md/architecture/overview)

---

# Codebase Tour

Map the main AgentClash modules before you start changing workflows, APIs, or the web UI.

Source: https://agentclash.dev/docs/contributing/codebase-tour
Markdown export: https://agentclash.dev/docs-md/contributing/codebase-tour

This repo is easier to navigate if you follow the runtime path instead of reading directories alphabetically.

## Start with the product surfaces

The main user-facing modules are:

- `web/`: the Next.js product site, authenticated app, and docs surface
- `cli/`: the standalone Go CLI used against local or hosted backends
- `backend/`: API and worker-side Go services
- `docs/`: deeper architecture, build-order, replay, and local-development notes

If you only remember one thing, remember this: the web app is not the whole product. AgentClash is a multi-service system with a CLI and a workflow engine behind it.

## Follow a run from request to evidence

A useful mental path through the repo is:

```mermaid
flowchart LR
  WEB[web/] --> API[backend/internal/api]
  API --> WF[Temporal workflows]
  WF --> WRK[backend/internal/worker]
  WRK --> SB[Sandbox provider]
  WRK --> EV[Replay events and artifacts]
  CLI[cli/] --> API
```

That is the shortest route from "user action" to "why did this run behave that way".

## Where to look for common tasks

### I need to change the web UX

Start in `web/src/app` for routes and page entry points, then `web/src/components` for the shared UI.

### I need to change auth or API behavior

Start in `backend/internal/api` and trace the handler path from request shape to domain logic.

### I need to change execution behavior

Start in `backend/internal/worker` and the orchestration docs so you understand what the workflow owns versus what the activity owns.

### I need to change local or hosted CLI behavior

Start in `cli/cmd` for command surface and `cli/internal` for config and supporting behavior.

### I need product context before I code

Start in `docs/` instead of guessing. The build-order, domain, replay, and database notes are there for a reason.

## A practical reading order for new contributors

1. Read [Setup](../contributing/setup).
2. Read [Overview](../architecture/overview).
3. Read [Orchestration](../architecture/orchestration).
4. Skim `docs/domains/domains.md` and `docs/database/schema-diagram.md`.
5. Only then start changing handlers, workflows, or UI.

That order is faster than diving straight into implementation files without the system model in your head.

## See also

- [Setup](../contributing/setup)
- [Testing](../contributing/testing)
- [Overview](../architecture/overview)
- [Frontend](../architecture/frontend)

---

# Testing

Choose the smallest useful validation loop and use review checkpoints to keep implementation work scoped.

Source: https://agentclash.dev/docs/contributing/testing
Markdown export: https://agentclash.dev/docs-md/contributing/testing

Testing in AgentClash should match the surface you changed. Do not default to the biggest possible loop.

## Pick the smallest loop that can prove the change

A useful rule is:

- docs or web route changes: start with `pnpm build` in `web/`
- CLI changes: use the `cli/` module commands and tests
- packaging changes: rehearse the release flow instead of guessing
- workflow or backend changes: validate the specific service path you touched

For CLI work, the repo already gives you a concrete baseline:

```bash
cd cli
go build ./...
go vet ./...
go test -short -race -count=1 ./...
go run github.com/goreleaser/goreleaser/v2@latest check
go run github.com/goreleaser/goreleaser/v2@latest release --snapshot --clean
```

## Use review checkpoints for implementation work

When the change is more than a one-line fix, lock the contract before you start coding.

The review-checkpoint workflow is simple:

1. create `testing/<branch-or-task>.md`
2. write the scope, functional expectations, tests, manual verification, and non-goals
3. treat that contract as fixed until requirements explicitly change
4. after each implementation step, update `/tmp/reviewcheckpoint.json`
5. run the scoped verification listed in the contract before you declare the work ready

This does two things well:

- it prevents scope drift
- it makes agent-assisted changes auditable instead of magical

> Note: Keep `/tmp/reviewcheckpoint.json` local scratch only. It is a working review log,
> not repo content.

## What to record in each checkpoint

A good checkpoint update includes:

- the current step number
- which files changed
- which contract items were addressed
- self-review result for that step
- cumulative review result across all steps so far
- unresolved risks

That cumulative review matters. It is how you catch drift after several small edits have accumulated.

## Manual verification still matters

Not every useful check is a unit test. For docs, routing, and UI work, manual verification is often part of the contract. Be explicit about it.

Examples:

- opening a docs route and confirming it renders
- confirming a public route bypasses auth middleware correctly
- verifying a generated reference page actually contains generated content

## See also

- [Codebase Tour](../contributing/codebase-tour)
- [Setup](../contributing/setup)
- [CLI Reference](../reference/cli)
- [Config Reference](../reference/config)