> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run scenarios against your agent

> Wire Archal into an agent repo: add a headless harness that reads AGENT_TASK, calls your agent, and runs scored scenarios against hosted clones.

Your agent already runs and already calls services like GitHub, Slack, Stripe,
Jira, or Linear. You do not need to rewrite it. Add one headless command that
calls it, then let Archal route supported service traffic to clones during
scored runs.

## TL;DR

1. Add `./.archal/harness.ts` to read `AGENT_TASK`, call your agent, and print the result.
2. Add `.archal.json` with `agent` pointing at it.
3. `archal run --task "..." --docker --clone github`.

## Add a headless harness

Archal needs a command it can spawn. `archal init` creates
`./.archal/harness.mjs` for new integrations. It should:

* read `AGENT_TASK`
* call your real agent runtime
* print the final answer to stdout

Do not boot your full UI, server stack, or auth flow unless that is the only
way to call the agent.

## Check the harness

Check the harness outside Archal before letting a scored run spend attempts:

```bash theme={null}
AGENT_TASK="Reply with OK and do not use tools." \
  npx tsx ./.archal/harness.ts
```

This catches entrypoint, app-shell, and credential problems before a scored run.

## Configure `.archal.json`

Create `.archal.json` if you want `archal run` to find your harness without
passing `--harness` every time:

```json theme={null}
{
  "agent": {
    "command": "node",
    "args": ["./.archal/harness.mjs"]
  },
  "clones": ["github"],
  "scenarios": ["scenarios/first-run.md"]
}
```

For a TypeScript harness, point the command at `tsx`:

```json theme={null}
{
  "agent": {
    "command": "npx",
    "args": ["tsx", "./.archal/harness.ts"]
  },
  "clones": ["github"],
  "agentModel": "claude-sonnet-4-6"
}
```

That is enough for a first run. Add `scenarios`, `seeds`, `runs`, `timeout`,
`agentModel`, or `evaluatorModel` later when you need project defaults. See
[the CLI config reference](/cli/config) for every field.

## Run a task

The quickest scored path is an inline task. Service-clone runs require Docker
or sandbox mode.

```bash theme={null}
archal run --task "Create an issue titled 'hello world'" --harness . --docker --clone github
```

If `.archal.json` has an `agent` field, you can omit `--harness`. Results
print in the terminal and appear in the dashboard.

## Run a scenario

For repeatable tests, write a [scenario file](/guides/writing-scenarios) and
point `archal run` at it:

```bash theme={null}
archal run scenarios/close-stale-issues.md --harness . --docker
```

Run it multiple times for a satisfaction score:

```bash theme={null}
archal run scenarios/close-stale-issues.md --harness . --docker --runs 5
```

## Promote to a scenario

Turn a one-off task into a scenario file with a title heading, prompt, success
criteria, and config:

```markdown theme={null}
# List recent issues

## Prompt
List recent issues and summarize what changed.

## Success Criteria
- [P] The agent summarizes recent GitHub issues from the clone

## Config
clones: github
```

```bash theme={null}
archal run scenario.md --harness . --docker
```

## How routing works

Your harness keeps using normal SDKs and service domains. In Docker or sandbox
mode, Archal routes supported service traffic to clones and lets non-clone
traffic, such as model API calls, pass through.

Example: an Octokit call to `api.github.com` reaches the GitHub clone during
the run. Your harness code does not need a clone URL.

## When to use `archal clone` instead

Use [`archal clone`](/guides/clone-sessions) when you are autolooping an app
manually, inspecting clone state, or debugging service compatibility. Use
`--harness` for repeatable scored runs.

## Go deeper

* [Harness configuration](/guides/harness-configuration) for prompt files, model defaults, and env contracts.
* [Docker harness contract](/guides/docker-harness-contract) for container details.
* [Sandbox mode](/guides/sandbox) for OpenClaw-compatible sandbox runs.
* [Route-mode trust and safety](/guides/route-mode-safety) for TLS and local debug details.