Clone sessions

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

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:

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.

Inspect and manage them

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:

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

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.

{
  "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:

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

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.

Start here

Test agents

Run anywhere

Advanced

Clone sessions

Start clones

Inspect and manage them

Use the returned URLs

Environment variables

Inspect with MCP

Inner loop: reuse a clone session across many runs

Seed Or Reset A Clone

​Start clones

​Inspect and manage them

​Use the returned URLs

​Environment variables

​Inspect with MCP

​Inner loop: reuse a clone session across many runs

​Seed Or Reset A Clone

Start clones

Inspect and manage them

Use the returned URLs

Environment variables

Inspect with MCP

Inner loop: reuse a clone session across many runs

Seed Or Reset A Clone