Skip to main content
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:
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:
For a TypeScript harness, point the command at tsx:
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.
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:
Run it multiple times for a satisfaction score:

​
Promote to a scenario

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

​
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 when you are autolooping an app manually, inspecting clone state, or debugging service compatibility. Use --harness for repeatable scored runs.

​
Go deeper