archal twin

Start persistent hosted twins for debugging, prompt iteration, and integration work.

Use archal twin when you want hosted twins to stay alive outside the normal archal run lifecycle.

This is the right workflow for:

• manual debugging against a stable GitHub, Jira, Slack, Stripe, or Supabase twin
• 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 twin before you build a scored scenario around it

Start twins

archal twin start github jira

That provisions a persistent hosted session and prints the MCP URL and REST base URL for each requested twin, 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 twin stop` to tear down, or `archal twin renew 7200` to extend.

You can also:

• start everything with archal twin start --all
• preload named seeds with archal twin start github --seed github:rich-org
• describe desired state with archal twin start github --setup "org with repos and CI"
• request a longer lifetime with archal twin start github --ttl-seconds 7200

Inspect and manage them

archal twin status
archal twin list
archal twin renew 7200
archal twin stop

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

Use the returned URLs

archal twin start prints API base URLs for each twin. 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 twin: you get a persistent hosted twin 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 twin with the route-mode environment and proxy flow described in the route-mode trust guide. archal twin keeps the twin alive; it does not execute your app or score the result.

Inner loop: reuse a twin 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 twin 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 twins

archal twin 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 twin 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 twin 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 twin seed github rich-org
archal twin seed github --file ./github.seed.js
archal twin seed github --setup "org with repos and CI"
archal twin 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 twins and score the result with a scenario.
• Use archal/vitest when you want hosted twins inside a Vitest workspace.
• Use archal scenario list when you want to browse runnable scenarios before starting a hosted twin session.

Trust and cleanup

archal twin 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 twin domains are rerouted

Read Route-mode trust and safety before using that attach path.