Introduction to Archal

Agents can change real systems: close issues, send messages, refund payments, grant access, and update records. Unit tests and mocks miss the hard failures: stale context, wrong permissions, bad ordering, and unsafe cross-tool actions. Archal lets you test those agents before production. It gives you hosted clones of the SaaS services your code already uses - GitHub, Slack, Stripe, Linear, and more. Point your agent at the clones, run a task, then read the score and trace. Clones aren’t mocks:

• they hold state across calls
• they enforce referential integrity between objects
• they return the same error shapes as the real service

​

When to use which entrypoint

• archal run - scenario runner. Markdown describes setup, task, and success criteria; Archal provisions clones, runs your code, evaluates the result.
• archal clone start - persistent clone session with live API endpoints. Right for debugging, prompt iteration, or wiring up a new integration. Pair with archal run --reuse-session for a fast inner loop that skips the cold-start.
• archal/vitest - hosted clones inside an existing Vitest suite. Tests use normal SDK clients; route mode redirects traffic to clones.

Same runtime in all three. The wrapping is different.

​

Concepts

​

Go deeper

• Use an existing agent repo to wire Archal into code that already runs.
• Write scenarios to make repeatable checks.
• Use persistent clones for stable SDK, REST, or MCP endpoints.
• Run in CI when you are ready to gate changes.
• Read security for credentials, telemetry, and session cleanup.