Architecture
Archal runs your agent against clones - isolated, service-shaped test environments with evidence-scoped fidelity. Clones run in isolated containers. For supported clone traffic, controlled Docker/sandbox runs and explicit clone URLs avoid production service APIs. Unsupported and non-clone network traffic is not simulated unless you block it in your harness environment.Credential handling
Archal stores local CLI credentials under~/.archal/. credentials.json stores email, plan, selected clone ids, expiry, and encrypted token fields. On macOS, the encryption key is stored in Keychain when available; otherwise Archal uses credentials.key or ARCHAL_CREDENTIALS_MASTER_KEY. archal logout removes the local credentials file.
Your agent’s own API keys (OpenAI, Anthropic, etc.) are resolved from environment variables or your config file. They are never sent to Archal servers.
Clone isolation
Default scored runs provision fresh clone state and tear it down when the run ends. If you usearchal clone start or archal run --reuse-session, the hosted session stays alive until you stop it or its TTL expires. Clones do not connect to real services.
Telemetry
Off by default. Enable withtelemetry: true in ~/.archal/config.json or ARCHAL_TELEMETRY=1.
When on, run traces can include tool calls, request parameters, clone responses, timestamps, scores, and errors. They power the dashboard and historical satisfaction tracking.
CLI analytics events go to PostHog. Before login, events use a generated
anonymous machine id. After login, events can include account identity, plan,
command name, scenario count, clone ids, duration, scores, and error codes.
They do not include scenario markdown or full tool-call payloads.
Controls
Telemetry is off by default. To explicitly disable it (or turn it off after enabling):Summary
Go deeper
- Authentication covers CLI login, tokens, and CI auth.
- Sandbox runtime covers how Archal runs agents safely.
- Route-mode safety covers SDK traffic routing and limits.