Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archal.ai/llms.txt

Use this file to discover all available pages before exploring further.

Reference for --harness. New to Archal? Start with Test your agent or Use an existing agent repo.

​
Prerequisites

  • archal login or ARCHAL_TOKEN
  • A model provider key (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY) if the harness calls a hosted model
  • A scenario markdown file

​
Repo-local harness

archal run scenario.md --harness ./.archal/harness.ts
archal run preflights the harness before provisioning hosted twins. A harness.json manifest alongside the entrypoint is optional — see Harness configuration. Point --harness at 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
Repo-local harnesses run locally by default. Pass --docker only when the harness needs to be built and run in a container.

​
Reproducing a preflight failure

ARCHAL_PREFLIGHT=1 ARCHAL_ENGINE_TASK="Reply with OK and do not use tools." \
  npx tsx ./.archal/harness.ts
Catches entrypoint, native-dependency, and service-bridge wiring issues independently of archal run’s own resolution path.

​
When to use archal twin instead

Use archal twin when you’re attaching an app manually, inspecting twin state, or debugging service compatibility. Come back to --harness for a repeatable scored run.