Skip to main content
Use this when your agent already runs and already calls services like GitHub, Slack, Stripe, Jira, or Linear. You do not need to rewrite the agent. 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.

​
1. Add a headless harness

Archal needs a runnable entrypoint it can start without booting your full app shell. The harness should:
  • read AGENT_TASK
  • call your agent runtime
  • print the final result to stdout as {"text": "..."} and keep logs on stderr. See Your first harness for the full stdout contract.
const task = process.env.AGENT_TASK?.trim();

if (!task) throw new Error('AGENT_TASK is required');

const result = await runMyAgent(task);
const text = typeof result === 'string' ? result : JSON.stringify(result);
console.log(JSON.stringify({ text }));

​
2. Check the harness

Check the harness outside Archal: 
AGENT_TASK="Reply with OK and do not use tools." \
  npx tsx ./.archal/harness.ts
This catches missing entrypoints, UI-only boot assumptions, and missing model credentials.

​
3. Add .archal.json

Optional with --harness, but useful as a project default: 
{
  "agent": {
    "command": "npx",
    "args": ["tsx", "./.archal/harness.ts"]
  },
  "clones": ["github"],
  "agentModel": "claude-sonnet-4-6"
}

​
4. Use normal service clients

Your harness should use normal SDKs and service domains. Archal routes supported service traffic to the scenario clones without exposing clone URLs to the agent process.

​
5. Choose the runtime

Use a local shell command only to check the harness entrypoint. For scored clone runs, use Docker for repo-local harnesses or run archal run ... --sandbox.

​
6. Run the first task

archal run --task "List recent issues" \
  --harness . \
  --docker \
  --clone github

​
7. Promote to a scenario

# 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

archal run scenario.md --harness . --docker