Skip to main content
Use --harness when you want archal run to start a specific agent entrypoint. 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

​
Basic use

For scored service-clone runs, point --harness at a repo or harness directory and use Docker: 
archal run scenario.md --harness . --docker
archal run scenario.md --harness ./my-agent --docker -n 3
For a direct entrypoint smoke test, run the harness from your shell instead of starting clones.

​
Runtime choice

Choose one controlled runtime for scored runs: 
# Repo-local harness directory
archal run scenario.md --harness . --docker

# Sandbox mode
archal run scenario.md --sandbox
A harness.json manifest is optional. Add one when you want default command args, prompt files, or a default model; see Harness configuration.

​
Checking the harness directly

AGENT_TASK="Reply with OK and do not use tools." \
  npx tsx ./.archal/harness.ts
This catches entrypoint, app-shell, and credential problems before a scored run.

​
When to use archal clone instead

Use archal clone when you’re autolooping an app manually, inspecting clone state, or debugging service compatibility. Use --harness for repeatable scored runs.