Skip to main content
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
  • autoloop 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: 
Session ses-01HXYZ... started (expires in 30m)

github
  MCP      https://ses-01hxyz.clones.archal.ai/github/mcp
  Base URL https://ses-01hxyz.clones.archal.ai/github/api

jira
  MCP      https://ses-01hxyz.clones.archal.ai/jira/mcp
  Base URL https://ses-01hxyz.clones.archal.ai/jira/api

Run `archal clone stop` to tear down, or `archal clone renew 7200` to extend.
You can also:
  • start everything with archal clone start --all
  • preload named seeds with archal clone start github --seed github:small-project
  • describe desired state with archal clone start github --setup "org with repos and CI"
  • request a longer lifetime with archal clone start github --ttl-seconds 7200
Startable clones are Apify, Cal.com, ClickUp, Customer.io, Datadog, Discord, GitHub, GitLab, Google Workspace, Jira, Linear, OwnerRez, PriceLabs, Ramp, SendGrid, Sentry, Slack, Stripe, Supabase, Tavily, Unipile, and Webflow.

​
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.ARCHAL_TOKEN,
});
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 and 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 exports per-clone URLs as environment variables so local tools, SDK clients, and harnesses can discover them without parsing CLI output.
VariableShapeDescription
ARCHAL_<CLONE>_REST_URLhttps://<session>.clones.archal.ai/<clone>/apiREST base URL for the clone
ARCHAL_<CLONE>_MCP_URLhttps://<session>.clones.archal.ai/<clone>/mcpMCP endpoint, only for clones with MCP support
ARCHAL_<CLONE>_URLsame as _MCP_URLLegacy MCP alias, only when MCP is supported
ARCHAL_TOKENbearer tokenAuth token for the session
<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 the exported variables would be: 
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 let the shell autoloop implicitly ...

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 (alias --no-reseed): explicitly keep the current clone state. Use this after sideloading state via archal clone seed --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 and reset them

archal clone seed github small-project
archal clone seed github --file ./github.seed.json
archal clone seed github --file ./github-seed.md
archal clone seed github --setup "org with repos and CI"
archal clone reset github
Use named seeds when you want a known starting point. Use --file with a .json or .md file when you need custom state for a specific integration test or debugging session.