Skip to main content
Use this guide when you already have an app or agent repo (Electron app, web shell, existing CLI, etc.) and want to run it with archal run. For a greenfield integration, start with Running Scenarios instead.

​
1. Add a headless harness

Archal needs a runnable entrypoint it can spawn without booting the full app shell. For new integrations, prefer ./.archal/harness.ts. That file should:
  • read ARCHAL_ENGINE_TASK
  • call the repo’s real agent runtime
  • exit cleanly when ARCHAL_PREFLIGHT=1
  • print the final result to stdout
Minimal shape: 
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 before a run

archal harness check ./.archal/harness.ts
That catches the common failures before a full twin session starts:
  • no runnable entrypoint
  • UI-only boot assumptions
  • missing model credentials
  • service bridge wiring issues

​
3. Decide whether .archal.json helps

.archal.json is optional when you pass --harness, but it is useful as a project-default path if you run Archal often from the same repo. 
{
  "agent": "npx tsx ./.archal/harness.ts",
  "twins": ["github"],
  "agentModel": "claude-sonnet-4-6"
}
Use it when you want:
  • a default agent command
  • default twins
  • default model and seed settings

​
4. Choose direct env vars or --proxy

Default path:
  • use ARCHAL_MCP_CONFIG
  • use ARCHAL_<TWIN>_URL
  • use ARCHAL_<TWIN>_BASE_URL
This is the preferred model when your runtime can point its MCP or REST clients at injected endpoints directly. Use --proxy only when the runtime still talks to real service domains through raw HTTPS clients and you want Archal to redirect that traffic without changing the agent code.

​
5. Ignore Docker unless you actually need it

Repo-local harnesses run locally by default. Use --docker only when the runtime depends on container-only system libraries or local bring-up is too messy to reproduce consistently.

​
6. Run the first task

archal run --task "List recent issues" \
  --harness ./.archal/harness.ts \
  --twin github
--task only replaces the scenario file. It still needs a runnable harness path from --harness, repo-local harness discovery, or .archal.json.

​
7. Turn that into a scenario

# List recent issues

## Prompt
List recent issues and summarize what changed.

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

## Config
twins: github
Run it with: 
archal run scenario.md --harness ./.archal/harness.ts

​
8. Find the artifacts afterward

Every run saves local artifacts under .archal/:
  • .archal/last-run.json
  • .archal/runs/*.json
Use --output json only when you need machine-readable stdout. It is not required for local trace saving.