Architecture
Archal runs your agent against clones - stateful behavioral copies of real services. Clones run in isolated containers. Your agent never touches production APIs during a test run.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
| Question | Answer |
|---|---|
| Does Archal touch my production services? | No. Clones are isolated behavioral copies. |
| Does Archal store my agent’s API keys? | No. They stay on your machine. |
| Does Archal send my agent’s tool calls to its servers? | Run traces are uploaded only when telemetry/tracing is enabled. CLI analytics are command-level and off by default. |
| Can I run Archal fully offline? | No. Clone provisioning requires the cloud control plane. |
| Where are my credentials stored? | ~/.archal/credentials.json, created by archal login. |
| How do I delete my data? | archal logout removes local credentials. Contact support@archal.ai for server-side account or trace deletion. |
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.