Skip to main content

​
Configure .archal.json

Create .archal.json in your project root: 
{
  "agent": "npx tsx src/my-agent.ts",
  "twins": ["github"]
}
FieldRequiredDescription
agentYesShell command to run your agent. Can be a string or an object with command, args, and env.
titleNoDisplay name for this project.
twinsNoWhich twins to start. If omitted, inferred from the scenario.
scenariosNoArray of scenario file paths relative to .archal.json.
seedsNoPer-twin seed names, e.g. { "github": "small-project" }.
agentModelNoLLM model for the agent (e.g. claude-sonnet-4-6).
modelNoEvaluator model (e.g. gemini-2.5-flash).
runsNoDefault number of runs per scenario. Default: 1.
timeoutNoDefault timeout per run in seconds. Default: 180.
The agent field also accepts an object for more control: 
{
  "agent": {
    "command": "node",
    "args": ["dist/agent.js"],
    "env": { "LOG_LEVEL": "debug" }
  },
  "twins": ["github", "slack"]
}

​
Run a task

The quickest way to test is an inline task: 
archal run --task "Create an issue titled 'hello world'" --twin github
If you have .archal.json with an agent field, Archal uses that command. Otherwise it runs the task directly.

​
Run a scenario

For repeatable tests, write a scenario file and point archal run at it: 
archal run scenarios/close-stale-issues.md
Run it multiple times for a satisfaction score: 
archal run scenarios/close-stale-issues.md --runs 5

​
How the proxy works

When you pass --proxy, Archal starts a local TLS proxy that intercepts your agent’s HTTPS traffic: 
archal run --task "..." --proxy
  |
  +-- 1. Read .archal.json (agent command, twins)
  +-- 2. Start cloud twin session
  +-- 3. Load seed data into twins
  +-- 4. Start local TLS proxy (generates a short-lived CA cert)
  +-- 5. Spawn agent with HTTPS_PROXY + NODE_EXTRA_CA_CERTS set
  |      Agent's HTTP calls get intercepted:
  |        api.github.com       -> github twin
  |        api.stripe.com       -> stripe twin
  |        api.anthropic.com    -> passthrough (not a twin)
  +-- 6. Agent completes, proxy stops
  +-- 7. Collect trace (every tool call + state mutations)
  +-- 8. Evaluate against success criteria -> satisfaction score
Traffic to non-twin domains passes through unmodified.

​
Supported runtimes

The proxy is language-agnostic (standard HTTPS CONNECT), but CA certificate injection varies:
RuntimeCA injectionNotes
Node.jsNODE_EXTRA_CA_CERTSAutomatic
PythonREQUESTS_CA_BUNDLE, SSL_CERT_FILEAutomatic

​
Intercepted domains

ServiceDomains routed to twin
GitHubapi.github.com, uploads.github.com
Google Workspacegmail.googleapis.com, calendar.googleapis.com, drive.googleapis.com, sheets.googleapis.com, people.googleapis.com, oauth2.googleapis.com
Slackslack.com/api/*
Stripeapi.stripe.com
Jira*.atlassian.net
Linearapi.linear.app
Supabase*.supabase.co
Discorddiscord.com, discordapp.com

​
Without the proxy

If your agent already talks to services via MCP tools (not raw HTTP), you don’t need --proxy. Archal passes MCP endpoints and REST base URLs as environment variables. Your agent uses those directly.

​
View results

Results print to the terminal. They also appear at archal.ai/dashboard.