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

# Clone sessions

> Keep hosted Archal clones alive between runs with archal clone start to debug against stable state, retry prompts, and attach local tools to fixed endpoints.

Use `archal clone` when you want hosted clones to stay alive while you debug.

Good uses:

* debug against stable service state
* retry prompts against the same data
* point local tools at fixed hosted endpoints
* exercise an existing app before writing a scored scenario

## Start clones

```bash theme={null}
archal clone start github jira
```

That provisions a hosted session and prints the MCP URL and REST base URL for
each requested clone, plus a session id and TTL. Realistic output:

```text theme={null}
Clone session ses-01HXYZ started

github
  REST: https://ses-01hxyz.clones.archal.ai/github/api
  MCP:  https://ses-01hxyz.clones.archal.ai/github/mcp
  Control auth: x-route-authorization: Bearer $ARCHAL_TOKEN

jira
  REST: https://ses-01hxyz.clones.archal.ai/jira/api
  MCP:  https://ses-01hxyz.clones.archal.ai/jira/mcp
  Control auth: x-route-authorization: Bearer $ARCHAL_TOKEN
```

Run `archal clone stop` to tear down, or `archal clone renew 7200` to extend.

For direct SDK or `curl` calls, export `ARCHAL_TOKEN` in the calling shell. CLI
login authenticates CLI commands, but your own process still needs a bearer
token for `x-route-authorization`.

You can also:

* start everything with `archal clone start --all`
* preload named seeds with `archal clone start github --seed github:small-project`
* request a longer lifetime with `archal clone start github --ttl-seconds 7200`

Run `archal clone` for the current hosted catalog, or read
[Clones overview](/clones/overview).

## Inspect and manage them

```bash theme={null}
archal clone status
archal clone list
archal clone renew 7200
archal clone stop
```

* `status` shows the active local session and its clone endpoints
* `list` shows all active hosted clone sessions for the current user
* `renew` extends the active session lifetime
* `stop` tears the active session down

## Use the returned URLs

`archal clone start` prints API base URLs for each clone. Use those URLs in your own local tools or SDK clients.

For example, for GitHub:

```ts theme={null}
import { Octokit } from '@octokit/rest';

const github = new Octokit({
  baseUrl: 'https://<session>.clones.archal.ai/github/api',
  auth: process.env.GITHUB_TOKEN ?? 'ghp_test_token_for_clone',
  request: {
    hook: (request, options) =>
      request({
        ...options,
        headers: {
          ...options.headers,
          'x-route-authorization': `Bearer ${process.env.ARCHAL_TOKEN}`,
        },
        request: { ...options.request, timeout: 10_000 },
      }),
  },
});
```

That fixed URL is the main reason to use `archal clone`.

When you use a service SDK against the printed base URL, set its normal test
auth value so the clone can exercise auth checks. When you send raw HTTP from
`curl`, a Lambda, or an edge worker instead of using the CLI or runtime helpers,
follow the two-header auth shape in [Direct API access](/guides/direct-api-access).

If your app needs route-mode interception instead of explicit base URLs, combine
`archal clone` with the route-mode environment/proxy flow described in the
[route-mode trust guide](/guides/route-mode-safety). `archal clone` keeps the
clone alive; it does not execute your app or score the result.

## Environment variables

`archal clone start` prints per-clone URLs. `archal clone status --json` exposes
the same values for tools, SDK clients, and harnesses that should not parse
human-readable CLI output.

| Value                     | Shape                                            | Description                                    |
| ------------------------- | ------------------------------------------------ | ---------------------------------------------- |
| `ARCHAL_<CLONE>_REST_URL` | `https://<session>.clones.archal.ai/<clone>/api` | REST base URL convention used by run harnesses |
| `ARCHAL_<CLONE>_MCP_URL`  | `https://<session>.clones.archal.ai/<clone>/mcp` | MCP endpoint convention when MCP is supported  |
| `ARCHAL_<CLONE>_URL`      | same as `_MCP_URL`                               | Legacy MCP alias convention                    |
| `ARCHAL_TOKEN`            | bearer token                                     | Route-control auth token                       |

`<CLONE>` is the clone id uppercased with non-alphanumeric characters replaced
by `_` (e.g., `github` becomes `GITHUB`, `google-workspace` becomes
`GOOGLE_WORKSPACE`).

For a GitHub clone, `archal clone status --json` exposes values equivalent to:

```bash theme={null}
ARCHAL_GITHUB_REST_URL=https://ses-01hxyz.clones.archal.ai/github/api
ARCHAL_GITHUB_MCP_URL=https://ses-01hxyz.clones.archal.ai/github/mcp
ARCHAL_GITHUB_URL=https://ses-01hxyz.clones.archal.ai/github/mcp
```

## Inspect with MCP

This is optional. Use the printed MCP URL when you want Claude Desktop, Cline,
Cursor, or another HTTP MCP client to inspect or edit clone state by hand.

```json theme={null}
{
  "mcpServers": {
    "archal-github": {
      "url": "https://<session>.clones.archal.ai/github/mcp",
      "headers": {
        "Authorization": "Bearer ${ARCHAL_TOKEN}"
      }
    }
  }
}
```

Restart the client after changing its config. Keep `ARCHAL_TOKEN` in an
environment variable or keychain-backed launcher; do not paste a literal token
into checked-in JSON.

This flow skips the scenario runner and evaluator. Use it to inspect state,
then use `archal run` when you want a scored result.

## Inner loop: reuse a clone session across many runs

To avoid a cold start on every run, start a session once and reuse it:

```bash theme={null}
archal clone start github --seed github:small-project
# ... copy the session id from the output, or reuse the shell's active session ...

archal run scenarios/close-stale-issues.md --docker --reuse-session              # single-session shell
archal run scenarios/close-stale-issues.md --docker --reuse-session ses-01hxyz   # explicit session id

# iterate... edit prompt or harness, re-run against the same live clones

archal clone stop
```

`--reuse-session` skips provisioning and never tears the session down at the
end of the run. Two related flags control seeding on a reused session:

* `--keep-state`: explicitly keep the current clone
  state. Use this after sideloading state via `archal clone seed <clone> --file`
  so your custom state is preserved between runs, even when it does not match
  the scenario's declared seed.
* `--fresh-seed`: force the scenario's declared seed to be re-applied,
  wiping any existing clone state first. Opposite of `--keep-state`.

`--fresh-seed` and `--keep-state` are mutually exclusive. By default, a reused
session is probed before seeding. If the clone already has state, Archal keeps
that state and warns instead of wiping it. If the clone is empty, Archal loads
the scenario's declared seed. Use `--fresh-seed` when you intentionally want to
reset the reused session to the scenario seed.

## Seed Or Reset A Clone

```bash theme={null}
archal clone seed github small-project
archal clone seed github --file ./github.seed.json
archal clone seed supabase --file ./supabase.seed.sql
archal clone reset github
```

Use named seeds when you want a known starting point. Use `--file` with a
`.json` or `.sql` file when you need custom state for a specific integration.