cac env

Each environment is a fully isolated context: its own .claude config, device identity, Claude Code version, and optional proxy.

create

Create a new environment.

cac env create <name> [-p <proxy>] [-c <version>] [--clone [source]] [--no-link] [--telemetry <mode>] [--persona <preset>]

Flag	Description
`-p, --proxy`	Proxy address. Optional.
`-c, --claude`	Claude Code version to pin. Auto-installs if not present. Use `latest` to resolve and pin the current latest version.
`--clone [source]`	Inherit config from `~/.claude/` (default) or another cac environment. Symlinks shared resources by default.
`--no-link`	Used with `--clone`. Copy files instead of symlink for independent customization.
`--telemetry <mode>`	Telemetry blocking mode: `transparent` (no blocking) / `stealth` (default, blocks 1p_events) / `paranoid` (maximum blocking). Backward compatible: old names `off` / `conservative` / `aggressive` auto-mapped.
`--persona <preset>`	Terminal environment preset for containers/servers: `macos-vscode` / `macos-cursor` / `macos-iterm` / `linux-desktop`. Injects desktop terminal env vars and hides Docker signals. Only needed if running in Docker/server.

The new environment is automatically activated after creation. Examples:

# Identity isolation only (no proxy, system Claude)
cac env create personal

# With proxy
cac env create work -p 1.2.3.4:1080:user:pass

# With proxy + pinned version
cac env create work -p socks5://proxy:1080 -c 2.1.81

# Resolve and pin latest Claude Code
cac env create dev -c latest

# Clone config from ~/.claude/ (symlinked)
cac env create work --clone

# Clone from another environment
cac env create work2 --clone work

# Clone with independent copies (no symlinks)
cac env create work --clone --no-link

# Stealth mode (default): blocks 1p_events but allows feature flags
cac env create stealth-env --telemetry stealth

# Paranoid mode: maximum telemetry blocking
cac env create paranoid --telemetry paranoid

# In Docker/server: use macOS VSCode persona
cac env create docker-work --persona macos-vscode

# Combine: Docker with strong telemetry blocking
cac env create secure-docker --persona macos-cursor --telemetry paranoid

Proxy formats:

host:port:user:pass       # auto-detect protocol (tries http → socks5 → https)
host:port                 # unauthenticated
socks5://user:pass@host:port
http://host:port

Environment names must be alphanumeric, dashes, or underscores. Names like my-work and prod_us1 are valid; my/work is not.

ls

List all environments.

cac env ls
cac ls        # shortcut

NAME        CLAUDE    PROXY                          ENV
▶ work      2.1.81    socks5://u:p@1.2.3.4:1080      local
  personal  system    —                              local

The ▶ marker shows the active environment.

activate

Activate an environment. This is global — affects all terminals.

cac env activate work
cac work              # shortcut

Activation:

Sets ~/.cac/current to the environment name
Updates statsig and user ID files in the isolated .claude config
Restarts relay if TUN is detected and proxy is configured

set

Modify a setting on an existing environment without recreating it.

cac env set [name] <key> <value>

If name is omitted, the currently active environment is used. Shorthand: cac env <name> <key> <value> (equivalent to cac env set <name> <key> <value>).

Proxy

cac env set work proxy socks5://user:pass@host:1080   # set or replace proxy
cac env set work proxy --remove                        # remove proxy

# Using shorthand
cac env work proxy socks5://user:pass@host:1080

# Target active env (omit name)
cac env set proxy socks5://user:pass@host:1080

Version

cac env set work version 2.1.81    # pin a specific version
cac env set work version latest    # resolve and pin the current latest

Telemetry mode

Change telemetry blocking strategy after environment creation.

cac env set work telemetry stealth      # default: blocks 1p_events, feature flags work
cac env set work telemetry paranoid     # maximum blocking, no telemetry
cac env set work telemetry transparent  # no blocking (relies on fingerprint spoofing)

Persona

Add or change terminal environment preset for container/server disguise.

cac env set work persona macos-vscode   # inject VSCode terminal env vars
cac env set work persona macos-cursor   # inject Cursor IDE env vars
cac env set work persona macos-iterm    # inject iTerm terminal env vars
cac env set work persona linux-desktop  # inject Linux desktop env vars
cac env set work persona --remove       # remove persona

check

Run diagnostics on the current active environment. Prints a concise conclusion with a pass/fail summary.

cac env check          # concise summary (✓/✗)
cac env check -d       # detailed output

Flag	Description
`-d, --details`	Show detailed diagnostic output instead of just the summary.

Checks:

Environment info (proxy, UUID, version, timezone)
Proxy connectivity and exit IP (if proxy configured)
TUN conflict detection (if proxy configured)
Security protections (DNS guard, telemetry env vars, mTLS)
Wrapper PATH detection

rm

Remove an environment. Cannot remove the active environment.

cac env rm staging

This permanently deletes the environment directory including its .claude config, identity files, and mTLS certificates.

Get started

Commands

create

ls

activate

set

Proxy

Version

Telemetry mode

Persona

check

rm

​create

​ls

​activate

​set

​Proxy

​Version

​Telemetry mode

​Persona

​check

​rm

create

ls

activate

set

Proxy

Version

Telemetry mode

Persona

check

rm