What is Archal?
Archal gives you hosted digital twins of the SaaS services your code depends on. Each twin is a stateful behavioral clone that maintains the same objects, relationships, error codes, and constraints as the real service. You run your code against the twins instead of production, and Archal captures a full trace of everything that happened so you can review it before shipping. The twins aren’t mocks; they hold state across calls, enforce referential integrity between objects, and return realistic errors when something goes wrong. If your code creates a GitHub issue and then lists open issues, the new one shows up. If it tries to send a Slack message to a channel that doesn’t exist, it gets back the same error shape Slack returns. That level of fidelity is what makes them useful for catching integration bugs that simpler test doubles miss.Agents
One use case for Archal is testing and evaluating AI agents. Agents make unpredictable sequences of API calls, and the consequences of getting those wrong are harder to reason about than traditional code paths. So we’ve built agent-specific workflows on top of the twin runtime: scenario-based evaluation with satisfaction scoring, inline task testing witharchal run --task, and a TLS proxy mode that intercepts an agent’s HTTP traffic and routes it to twins without any code changes.
That said, the twin runtime itself doesn’t care whether the code talking to it is an agent, a CI pipeline, a webhook handler, or a Vitest suite. The same hosted endpoints work for all of them.
How it works
There are three ways to use Archal, depending on what you’re trying to do.archal run is the scenario runner. You give it a markdown file that describes the starting state, the task, and what success looks like, and Archal provisions twins, runs your code against them, captures the trace, and evaluates the result. Basically evals in simulation environments.
archal twin start gives you a persistent session with live API endpoints. You point your code at those endpoints directly and interact with the twins for as long as you need. This is the right choice when you’re debugging, iterating on prompts, or wiring up a new integration and you want to poke at the twin state manually between calls. Using archal run task "" is useful here.
archal/vitest brings hosted twins into an existing Vitest test suite. Your tests use the standard SDK clients or HTTP clients and Archal’s route-mode adapter redirects traffic to twins behind the scenes.
Concepts
| Concept | What it means |
|---|---|
| Digital twin | A stateful behavioral clone of a real service, hosted by Archal. Not a mock or stub. |
| Scenario | A markdown file describing a test: the starting state, the task, and what success looks like. |
| Satisfaction | A percentage score (0-100) reflecting how well a run met the scenario’s success criteria, aggregated across multiple executions. |
| Seed | A predefined starting state for a twin. Built-in seeds cover common configurations, or you can describe the state you want in plain English and Archal generates it. |
| Trace | A complete record of every tool call and API request made during a run, with timestamps and state mutations. |
Next steps
Quickstart
Install, log in, and run your first test.
Test your agent
Configure .archal.json and run your own agent against twins.
Twins
See all available twins and how the runtime works.