Skip to main content
Reference doc for the --harness flag specifically. If you’re new to Archal and figuring out how to wire your agent in at all, start with Running Scenarios or (for an existing app) Use an existing agent repo. Use this workflow when you want Archal to execute your app’s real harness against hosted twins as part of a scenario.

​
Before you start

  • authenticate with archal login or ARCHAL_TOKEN
  • set a provider key such as ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY if your harness calls a hosted model directly
  • pick a scenario markdown file

​
Fastest path: use a repo-local headless harness

Make sure the repo exposes a headless harness entrypoint, usually ./.archal/harness.ts, then verify it: 
archal harness check ./.archal/harness.ts
archal run scenario.md --harness ./.archal/harness.ts
That gives you a real repo-local entrypoint Archal can boot, then the scored run once the harness checks pass.

​
Use your own local harness

Point --harness at either a file or a directory: 
archal run scenario.md --harness ./.archal/harness.ts --agent-model my-model
archal run scenario.md --harness ./my-agent -n 3
The preferred shape is a real harness program such as ./.archal/harness.ts inside the repo you want to test. Archal can still use an archal-harness.json manifest for compatibility, but that is not the primary model anymore. Repo-local harness paths run locally by default. Pass --docker only when you want Archal to build and run that harness repo in Docker.

​
Preflight before the real run

archal harness check ./.archal/harness.ts
Run that first when you are wiring up a new harness. It tells you whether the next problem is harness resolution, the entrypoint itself, or the local runtime environment.

​
When to use archal twin instead

Choose archal twin first when you are still attaching an app manually, inspecting twin state, or debugging service compatibility. Come back to archal run --harness once you want a repeatable scored run with proof.

​
When to use an engine endpoint instead

If your agent already runs behind a remote OpenClaw-compatible /v1/responses endpoint, skip --harness and use --engine-endpoint instead. That keeps Archal responsible for hosted twins and evaluation, while your own gateway stays responsible for execution. That endpoint needs to execute tool-calling runs and be able to reach the hosted twin MCP URLs Archal provides. A raw model API is not enough.