Skip to main content

​
Versions

A version is a Claude Code binary managed by cac. Binaries are downloaded from Anthropic’s official distribution and verified with SHA256 checksums. 
~/.cac/versions/
├── 2.1.81/claude      # specific version
├── 2.1.80/claude      # another version
└── .latest            # tracks which version is "latest"
You can have multiple versions installed simultaneously. Each environment can pin a different version. 
cac claude install latest
cac claude install 2.1.81
cac claude ls

​
Environments

An environment is a complete, isolated context for running Claude Code. It includes:
ComponentWhat’s isolated
.claude/ configSessions, settings, project memory, auth tokens
Device identityUUID, hostname, MAC address, machine ID, stable ID
Claude Code versionPinned binary (or system default)
ProxyOptional network route
mTLS certificatePer-environment client cert signed by cac’s CA
~/.cac/envs/work/
├── .claude/            # isolated CLAUDE_CONFIG_DIR
├── proxy               # proxy URL (optional)
├── version             # pinned Claude Code version
├── uuid                # fake hardware UUID
├── hostname            # fake hostname
├── mac_address         # fake MAC
├── machine_id          # fake /etc/machine-id
├── stable_id           # fake statsig ID
├── user_id             # fake user ID
├── client_cert.pem     # mTLS client certificate
└── type                # "local" or "container"

​
Activation

Activating an environment is global — it affects all terminals and all project directories. This is by design: your identity and proxy route are per-user concerns, not per-project. 
cac work              # activate "work" environment
cac env deactivate    # go back to unprotected mode
When activated, the cac wrapper intercepts every claude invocation and applies the environment’s settings.

​
Proxy is optional

Two types of users:
User typeSetupWhat cac does
Proxy usercac env create work -p proxyFingerprint isolation + proxy routing + telemetry blocking
API key usercac env create workFingerprint isolation + telemetry blocking (keeps ANTHROPIC_API_KEY)
When no proxy is configured, cac preserves your ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, and ANTHROPIC_AUTH_TOKEN environment variables. When a proxy is configured, these are cleared to force OAuth authentication through the proxy.

​
Auto-install

When you reference a version that isn’t installed yet, cac downloads it automatically — just like uv auto-installs Python versions: 
# Version 2.1.81 not installed? cac downloads it first, then creates the env.
cac env create work -c 2.1.81

​
Auto-relay

If cac detects TUN-mode proxy software (Clash, Surge, sing-box) running on your system, it automatically starts a local TCP relay. This prevents the double-proxy problem where TUN wraps cac’s proxy traffic. 
claude ──► wrapper ──► relay (127.0.0.1) ──► remote proxy ──► API
                        ↑ loopback bypasses TUN
No user action needed — relay activates and deactivates automatically.