Skip to main content

​
Architecture

Archal runs your agent against digital twins — stateful behavioral clones of real services. Twins run in isolated containers. Your agent never touches production APIs during a test run.

​
Credential handling

Archal stores authentication credentials in ~/.archal/credentials.json. This file contains your JWT token, email, plan, and a list of available twins. The file is created by archal login and removed by archal logout. 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.

​
Twin isolation

Each run provisions a fresh set of twins. Twin state is ephemeral — it exists only for the duration of the run and is destroyed afterward. Twins do not connect to real services and cannot make outbound network requests.

​
Trace uploads

Telemetry is disabled by default. Trace uploads, product analytics, and managed trace storage are all opt-in. Nothing is sent unless you explicitly enable telemetry.
If you enable telemetry (telemetry: true in ~/.archal/config.json), trace data from your runs is uploaded to Archal servers. Traces include every tool call your agent made during a run — the request parameters, the twin’s response, and timestamps. Traces are used to power the dashboard, historical satisfaction tracking, and debugging. You can disable trace uploads at any time by setting telemetry: false or unsetting the ARCHAL_TELEMETRY environment variable.

​
Analytics

If telemetry is enabled (off by default), anonymized usage events are sent to PostHog. These events include:
  • CLI command invoked (e.g. run, twin, login)
  • Scenario count and twin types used
  • Run duration and satisfaction scores
  • Error codes (not error messages or stack traces)
Events are keyed by a one-way hash of your email — your email address is never sent to PostHog. No tool call content, agent prompts, or scenario text is included in analytics events.

​
Controls

Telemetry is off by default. To explicitly disable it (or turn it off after enabling): 
archal config set telemetry false
Or set the environment variable: 
export ARCHAL_TELEMETRY=false
To verify your current telemetry setting: 
archal config show

​
Summary

QuestionAnswer
Does Archal touch my production services?No. Twins are isolated behavioral clones.
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?Only if you enable telemetry. Off by default.
Can I run Archal fully offline?Not yet. Twin 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 data deletion.