> ## 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.

# Introduction to Archal

> Archal hosts service-shaped clones of GitHub, Slack, Stripe, Linear, and more so you can score, trace, and harden AI agents before they touch production.

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. Mature clone surfaces are stateful; architecture previews are
narrower and clearly labeled. 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

<CardGroup cols={2}>
  <Card title="I have an existing agent" icon="terminal" href="/guides/run-with-agent">
    Add Archal to a repo that already runs.
  </Card>

  <Card title="I need the first run" icon="rocket" href="/quickstart">
    Add a small harness and run one scored test.
  </Card>

  <Card title="I want manual endpoints" icon="plug" href="/guides/clone-sessions">
    Start persistent clones for SDK, REST, or MCP debugging.
  </Card>

  <Card title="I want test-suite integration" icon="flask-conical" href="/guides/vitest">
    Use hosted clones from Vitest.
  </Card>
</CardGroup>

## 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

|                                                                    |                                                                       |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **[Clone](/clones/overview)**                                      | Service-shaped test environment for a real service, hosted by Archal. |
| **[Scenario](/guides/writing-scenarios)**                          | Markdown file: setup, task, success criteria.                         |
| **Harness**                                                        | The command Archal runs to call your agent.                           |
| **[Satisfaction](/guides/writing-scenarios#how-evaluation-works)** | Score from `0` to `100` across one or more runs.                      |
| **[Seed](/guides/seeds)**                                          | Starting state for a clone. Built-in, file-backed, or replayed.       |
| **[Trace](/cli/debug)**                                            | Record of every tool call and API request, with state mutations.      |

## Go deeper

* [Run scenarios against your agent](/guides/run-with-agent) to wire Archal into code that already runs.
* [Write scenarios](/guides/writing-scenarios) to make repeatable checks.
* [Use persistent clones](/guides/clone-sessions) for stable SDK, REST, or MCP endpoints.
* [Run in CI](/guides/ci-integration) when you are ready to gate changes.
* [Read security](/security) for credentials, telemetry, and session cleanup.