Skip to main content
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 fake GitHub, Jira, Slack, Stripe, or Supabase surface
  • 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 API base URLs for each requested twin. 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.

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