Skip to main content

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.

Use archal clone when you want hosted clones to stay alive outside the normal archal run lifecycle. The legacy archal twin alias still works — every example on this page accepts either form. This is the right workflow for:
  • manual debugging against a stable GitHub, Jira, Slack, Stripe, or Supabase clone
  • prompt iteration when you want to retry the same state repeatedly
  • local integration work where your own tools need fixed hosted endpoints
  • attaching an existing app to a service clone before you build a scored scenario around it

​
Start clones

archal clone start github jira
That provisions a persistent 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.twins.archal.ai/github/mcp
  Base URL https://ses-01hxyz.twins.archal.ai/github/api

jira
  MCP      https://ses-01hxyz.twins.archal.ai/jira/mcp
  Base URL https://ses-01hxyz.twins.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:rich-org
  • 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

​
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>.twins.archal.ai/github/api',
});
That is the main reason to choose archal clone: you get a persistent hosted clone session that your own tooling can keep talking to between runs. If you are sending raw HTTP from curl, a Lambda, or an edge worker instead of using the CLI or runtime helpers, follow the 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.

​
Inner loop: reuse a clone session across many runs

When you’re iterating on a prompt or scenario and don’t want to pay the ~30-second cold-start on every run, start a session once and point each run at it with --reuse-session: 
archal clone start github --seed github:small-project
# ... copy the session id from the output, or let the shell attach implicitly ...

archal run scenarios/close-stale-issues.md --reuse-session              # single-session shell
archal run scenarios/close-stale-issues.md --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): skip the scenario’s named-seed re-apply. Use this after sideloading state via archal clone seed --file so your custom state is preserved between runs.
  • --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 — pass one or the other, never both. Default behavior (neither flag) re-applies the scenario’s named seed on every run.

​
Seed and reset them

archal clone seed github rich-org
archal clone seed github --file ./github.seed.js
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 when you need custom state for a specific integration test or debugging session.

​
When not to use this flow

  • Use archal run --harness when you want Archal to execute an agent against hosted clones and score the result with a scenario.
  • Use archal/vitest when you want hosted clones inside a Vitest workspace.
  • Use archal scenario list when you want to browse runnable scenarios before starting a hosted clone session.

​
Trust and cleanup

archal clone itself is just the hosted session lifecycle. If you later attach a local app through route mode:
  • Archal does not install a host OS trust root by default.
  • local route mode injects trust into the app process with env vars such as NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and CURL_CA_BUNDLE
  • the local CA is generated per run and cleaned up at teardown
  • only configured clone domains are rerouted
Read Route-mode trust and safety before using that attach path.