Use an existing agent repo

Bring an existing app or agent repo to Archal.

TL;DR

1. Add ./.archal/harness.ts — reads ARCHAL_ENGINE_TASK, calls your agent, prints the result.
2. Add .archal.json with agent pointing at it.
3. archal run --task "..." --twin github.

The rest of this page is the longer version.

1. Add a headless harness

Archal needs a runnable entrypoint it can spawn without booting the full app shell.

The harness should:

• short-circuit when ARCHAL_PREFLIGHT=1 so archal run can validate the entrypoint before provisioning twins:
  if (process.env.ARCHAL_PREFLIGHT === '1') {
    console.log('OK');
    process.exit(0);
  }
  
• read ARCHAL_ENGINE_TASK
• call your agent runtime
• print the final result to stdout as a JSON object like {"text": "..."} and keep logs on stderr. Archal extracts structured output in preference to plain text — see Your first harness for the full stdout contract.

const task = process.env.ARCHAL_ENGINE_TASK?.trim();

if (process.env.ARCHAL_PREFLIGHT === '1') {
  console.log('preflight ok');
  process.exit(0);
}

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

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

2. Check the harness

archal run preflights automatically. To reproduce a preflight failure outside Archal:

ARCHAL_PREFLIGHT=1 ARCHAL_ENGINE_TASK="Reply with OK and do not use tools." \
  npx tsx ./.archal/harness.ts

Catches: no entrypoint, UI-only boot assumptions, missing model credentials, service bridge wiring.

3. Add .archal.json

Optional with --harness, but useful as a project default:

{
  "agent": {
    "command": "npx",
    "args": ["tsx", "./.archal/harness.ts"]
  },
  "twins": ["github"],
  "agentModel": "claude-sonnet-4-6"
}

4. Service traffic

Your harness should use normal SDKs and service domains. Archal’s proxy routes supported service traffic to the scenario twins without exposing twin URLs to the agent process.

5. Skip Docker unless you need it

Repo-local harnesses run locally by default. Pass --docker only when the runtime depends on container-only system libraries.

6. Run the first task

archal run --task "List recent issues" \
  --harness ./.archal/harness.ts \
  --twin github

7. Promote to a scenario

# List recent issues

## Prompt
List recent issues and summarize what changed.

## Success Criteria
- [D] The run exits successfully

## Config
twins: github

archal run scenario.md --harness ./.archal/harness.ts

8. Find the artifacts

.archal/cache/last-run.json and .archal/cache/runs/*.json. Use --output json only for machine-readable stdout.

Related

• Test your agent
• archal run —harness
• Your first harness