Skip to main content
Read this when you are wiring Archal into an agent repo.

​
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.

​
Configure .archal.json

Create .archal.json if you want archal run to find your harness without passing --harness every time: 
{
  "agent": {
    "command": "node",
    "args": ["./.archal/harness.mjs"]
  },
  "clones": ["github"],
  "scenarios": ["scenarios/first-run.md"]
}
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 for every field.

​
Run a task

The quickest scored path is an inline task. Service-clone runs require Docker or sandbox mode. 
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 and point archal run at it: 
archal run scenarios/close-stale-issues.md --harness . --docker
Run it multiple times for a satisfaction score: 
archal run scenarios/close-stale-issues.md --harness . --docker --runs 5

​
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.

​
Go deeper