GitHub - nmhjklnm/cac: Isolate, protect, and manage your Claude Code

Claude Code 小雨衣 — Isolate, protect, and manage your Claude Code.

Run Claude Code your way — isolated, protected, managed.

中文 | English | 📖 Docs

⭐ Star this repo if it helps — it helps others find it too.

中文

Switch to English

简介

cac 是 Claude Code 的环境管理器，类似 uv 之于 Python：

版本管理 — 安装、切换、回滚 Claude Code 版本
环境隔离 — 每个环境独立的 .claude 配置 + 身份 + 代理
隐私保护 — 设备指纹伪装 + 遥测分级（conservative/aggressive）+ mTLS
配置继承 — --clone 从宿主或其他环境继承配置，~/.cac/settings.json 全局偏好
零配置 — 无需 setup，首次使用自动初始化

注意事项

封号风险说明：cac 提供设备指纹层保护（UUID、主机名、MAC、遥测阻断、配置隔离），但无法影响账号层风险——包括 OAuth 账号本身、支付方式指纹、IP 信誉评分，以及 Anthropic 的服务端封禁决策。封号是账号层问题，cac 对此无能为力。详见封号风险 FAQ。

代理工具冲突：如果本地启动了 Clash、Shadowrocket、Surge、sing-box 等代理/VPN 工具，建议在使用 cac 时先关闭。TUN 模式兼容性仍属实验性功能。即使发生冲突，cac 也会自动停止连接（fail-closed），不会泄露你的真实 IP。

首次登录：启动 claude 后，输入 /login 完成 OAuth 授权
安全验证：随时运行 cac env check 确认隐私保护状态，也可以 which claude 确认使用的是 cac 托管的 claude
自动安全检查：每次启动 Claude Code 会话时，cac 会快速检查环境。如有异常会终止会话，不会发送任何数据
网络稳定性：流量严格走代理——代理断开时流量完全停止，不会回退直连。内置心跳检测和自动恢复，断线后无需手动重启
IPv6：建议系统级关闭，防止真实地址泄露

安装

# npm（推荐）
npm install -g claude-cac

# 或手动安装
curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash

快速上手

# 安装 Claude Code
cac claude install latest

# 创建环境（自动激活，自动使用最新版）
cac env create work -p 1.2.3.4:1080:u:p

# 启动 Claude Code（首次需 /login）
claude

代理可选 — 不需要代理也能用：

cac env create personal                  # 只要身份隔离
cac env create work -c 2.1.81           # 指定版本，无代理

版本管理

cac claude install latest               # 安装最新版
cac claude install 2.1.81               # 安装指定版本
cac claude ls                           # 列出已安装版本
cac claude pin 2.1.81                   # 当前环境切换版本
cac claude uninstall 2.1.81             # 卸载

环境管理

cac env create <name> [-p <proxy>] [-c <version>]   # 创建并自动激活（自动解析最新版）
cac env ls                              # 列出所有环境
cac env rm <name>                       # 删除环境
cac env set [name] proxy <url>          # 设置 / 修改代理
cac env set [name] proxy --remove       # 移除代理
cac env set [name] version <ver>        # 切换版本
cac <name>                              # 激活环境（快捷方式）
cac ls                                  # = cac env ls

每个环境完全隔离：

Claude Code 版本 — 不同环境可以用不同版本
.claude 配置 — sessions、settings、memory 各自独立
身份信息 — UUID、hostname、MAC 等完全不同
代理出口 — 每个环境走不同代理（或不走代理）

全部命令

命令	说明
版本管理
`cac claude install [latest\|<ver>]`	安装 Claude Code
`cac claude uninstall <ver>`	卸载版本
`cac claude ls`	列出已安装版本
`cac claude pin <ver>`	当前环境绑定版本
环境管理
`cac env create <name> [-p proxy] [-c ver] [--clone] [--telemetry mode] [--persona preset]`	创建环境（自动激活，`--telemetry transparent/stealth/paranoid` 控制遥测，`--persona macos-vscode/...` 用于容器）
`cac env ls`	列出环境
`cac env rm <name>`	删除环境
`cac env set [name] <key> <value>`	修改环境（proxy / version / telemetry / persona）
`cac env check [-d]`	验证当前环境（`-d` 显示详情）
`cac <name>`	激活环境
自管理
`cac self update`	更新 cac 自身
`cac self delete`	卸载 cac
其他
`cac ls`	列出环境（= `cac env ls`）
`cac check`	检查当前环境（`cac env check` 的别名）
`cac -v`	版本号

代理格式

host:port:user:pass       带认证（自动检测协议）
host:port                 无认证
socks5://u:p@host:port    指定协议

隐私保护

特性	实现方式
硬件 UUID 隔离	macOS `ioreg` / Linux `machine-id` / Windows `wmic`+`reg` shim
主机名 / MAC 隔离	Shell shim + Node.js `os.hostname()` / `os.networkInterfaces()` hook
Node.js 指纹钩子	`fingerprint-hook.js` 通过 `NODE_OPTIONS --require` 注入
遥测阻断	DNS guard + 环境变量 + fetch 拦截 + 分级模式（`conservative`/`aggressive`）
健康检查 bypass	进程内 Node.js 拦截（无需 /etc/hosts 或 root）
mTLS 客户端证书	自签 CA + 每环境独立客户端证书
`.claude` 配置隔离	每个环境独立的 `CLAUDE_CONFIG_DIR`

工作原理

              cac wrapper（进程级，零侵入源代码）
              ┌──────────────────────────────────────────┐
  claude ────►│  CLAUDE_CONFIG_DIR → 隔离配置目录          │
              │  版本解析 → ~/.cac/versions/<ver>/claude   │
              │  健康检查 bypass（进程内拦截）                │
              │  12 层遥测环境变量保护                      │──► 代理 ──► Anthropic API
              │  NODE_OPTIONS: DNS guard + 指纹钩子        │
              │  PATH: 设备指纹 shim                       │
              │  mTLS: 客户端证书注入                       │
              └──────────────────────────────────────────┘

文件结构

~/.cac/
├── versions/<ver>/claude     # Claude Code 二进制文件
├── bin/claude                # wrapper
├── shim-bin/                 # ioreg / hostname / ifconfig / cat shim
├── fingerprint-hook.js       # Node.js 指纹拦截
├── cac-dns-guard.js          # DNS + fetch 遥测拦截
├── ca/                       # 自签 CA + 健康检查 bypass 证书
├── current                   # 当前激活的环境名
└── envs/<name>/
    ├── .claude/              # 隔离的 .claude 配置目录
    │   ├── settings.json     # 环境专属设置
    │   ├── CLAUDE.md         # 环境专属记忆
    │   └── statusline-command.sh
    ├── proxy                 # 代理地址（可选）
    ├── version               # 绑定的 Claude Code 版本
    ├── uuid / stable_id      # 隔离身份
    ├── hostname / mac_address / machine_id
    └── client_cert.pem       # mTLS 证书

Docker 容器模式

完全隔离的运行环境：sing-box TUN 网络隔离 + cac 身份伪装，预装 Claude Code。

cac docker setup     # 粘贴代理地址，网络自动检测
cac docker start     # 启动容器
cac docker enter     # 进入容器，claude + cac 直接可用
cac docker check     # 网络 + 身份一键诊断
cac docker port 6287 # 端口转发

代理格式：ip:port:user:pass（SOCKS5）、ss://...、vmess://...、vless://...、trojan://...

English

切换到中文

Overview

cac — Isolate, protect, and manage your Claude Code:

Version management — install, switch, rollback Claude Code versions
Environment isolation — independent .claude config + identity + proxy per environment
Privacy protection — device fingerprint spoofing + telemetry modes (conservative/aggressive) + mTLS
Config inheritance — --clone inherits config from host or other envs, ~/.cac/settings.json for global preferences
Zero config — no setup needed, auto-initializes on first use

Notes

Account ban notice: cac provides device fingerprint layer protection (UUID, hostname, MAC, telemetry blocking, config isolation), but cannot affect account-layer risks — including your OAuth account, payment method fingerprint, IP reputation score, or Anthropic's server-side ban decisions. Account bans are an account-layer issue that cac does not address. See the Ban Risk FAQ for details.

Proxy tool conflicts: If you have Clash, Shadowrocket, Surge, sing-box or other proxy/VPN tools running locally, turn them off before using cac. TUN-mode compatibility is still experimental. Even if a conflict occurs, cac will fail-closed — your real IP is never exposed.

First login: Run claude, then type /login. Health check is automatically bypassed.
Verify your setup: Run cac env check anytime. Use which claude to confirm you're using the cac-managed wrapper.
Automatic safety checks: Every new Claude Code session runs a quick cac check. If anything is wrong, the session is terminated before any data is sent.
Network resilience: Traffic is strictly routed through your proxy. If the proxy drops, traffic stops entirely — no fallback to direct connection. Built-in heartbeat detection and auto-recovery — no manual restart needed after disconnections.
IPv6: Recommend disabling system-wide to prevent real address exposure.

Install

# npm (recommended)
npm install -g claude-cac

# or manual
curl -fsSL https://raw.githubusercontent.com/nmhjklnm/cac/master/install.sh | bash

Quick start

# Install Claude Code
cac claude install latest

# Create environment (auto-activates, auto-resolves latest version)
cac env create work -p 1.2.3.4:1080:u:p

# Run Claude Code (first time: /login)
claude

Proxy is optional:

cac env create personal                  # identity isolation only
cac env create work -c 2.1.81           # pinned version, no proxy

Version management

cac claude install latest               # install latest
cac claude install 2.1.81               # install specific version
cac claude ls                           # list installed versions
cac claude pin 2.1.81                   # pin current env to version
cac claude uninstall 2.1.81             # remove

Environment management

cac env create <name> [-p <proxy>] [-c <version>]   # create and auto-activate (auto-resolves latest)
cac env ls                              # list all environments
cac env rm <name>                       # remove environment
cac env set [name] proxy <url>          # set / change proxy
cac env set [name] proxy --remove       # remove proxy
cac env set [name] version <ver>        # change version
cac <name>                              # activate (shortcut)
cac ls                                  # = cac env ls

Each environment is fully isolated:

Claude Code version — different envs can use different versions
.claude config — sessions, settings, memory are independent
Identity — UUID, hostname, MAC are all different
Proxy — each env routes through a different proxy (or none)

All commands

Command	Description
Version management
`cac claude install [latest\|<ver>]`	Install Claude Code
`cac claude uninstall <ver>`	Remove version
`cac claude ls`	List installed versions
`cac claude pin <ver>`	Pin current env to version
Environment management
`cac env create <name> [-p proxy] [-c ver] [--clone] [--telemetry mode] [--persona preset]`	Create environment (auto-activates, `--telemetry transparent/stealth/paranoid` for telemetry control, `--persona macos-vscode/...` for containers)
`cac env ls`	List environments
`cac env rm <name>`	Remove environment
`cac env set [name] <key> <value>`	Modify environment (proxy / version / telemetry / persona)
`cac env check [-d]`	Verify current environment (`-d` for details)
`cac <name>`	Activate environment
Self-management
`cac self update`	Update cac itself
`cac self delete`	Uninstall cac
Other
`cac ls`	List environments (= `cac env ls`)
`cac check`	Verify environment (alias for `cac env check`)
`cac -v`	Show version

Privacy protection

Feature	How
Hardware UUID isolation	macOS `ioreg` / Linux `machine-id` / Windows `wmic`+`reg` shim
Hostname / MAC isolation	Shell shim + Node.js `os.hostname()` / `os.networkInterfaces()` hook
Node.js fingerprint hook	`fingerprint-hook.js` via `NODE_OPTIONS --require`
Telemetry blocking	DNS guard + env vars + fetch interception + modes (`conservative`/`aggressive`)
Health check bypass	In-process Node.js interception (no `/etc/hosts`, no root)
mTLS client certificates	Self-signed CA + per-profile client certs
`.claude` config isolation	Per-environment `CLAUDE_CONFIG_DIR`

How it works

              cac wrapper (process-level, zero source invasion)
              ┌──────────────────────────────────────────┐
  claude ────►│  CLAUDE_CONFIG_DIR → isolated config dir   │
              │  Version resolve → ~/.cac/versions/<ver>   │
              │  Health check bypass (in-process intercept) │
              │  Env vars: 12-layer telemetry kill         │──► Proxy ──► Anthropic API
              │  NODE_OPTIONS: DNS guard + fingerprint     │
              │  PATH: device fingerprint shims            │
              │  mTLS: client cert injection               │
              └──────────────────────────────────────────┘

File layout

~/.cac/
├── versions/<ver>/claude     # Claude Code binaries
├── bin/claude                # wrapper
├── shim-bin/                 # ioreg / hostname / ifconfig / cat shims
├── fingerprint-hook.js       # Node.js fingerprint interception
├── cac-dns-guard.js          # DNS + fetch telemetry interception
├── ca/                       # self-signed CA + health bypass cert
├── current                   # active environment name
└── envs/<name>/
    ├── .claude/              # isolated .claude config directory
    │   ├── settings.json     # env-specific settings
    │   ├── CLAUDE.md         # env-specific memory
    │   └── statusline-command.sh
    ├── proxy                 # proxy URL (optional)
    ├── version               # pinned Claude Code version
    ├── uuid / stable_id      # isolated identity
    ├── hostname / mac_address / machine_id
    └── client_cert.pem       # mTLS cert

Docker mode

Fully isolated environment: sing-box TUN network isolation + cac identity protection, with Claude Code pre-installed.

cac docker setup     # paste proxy, network auto-detected
cac docker start     # start container
cac docker enter     # shell with claude + cac ready
cac docker check     # network + identity diagnostics
cac docker port 6287 # port forwarding

Proxy formats: ip:port:user:pass (SOCKS5), ss://..., vmess://..., vless://..., trojan://...

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
.github/workflows		.github/workflows
.playwright-mcp		.playwright-mcp
.vscode		.vscode
docker		docker
docs		docs
mitm		mitm
scripts		scripts
src		src
.gitignore		.gitignore
Dockerfile.real-test		Dockerfile.real-test
Dockerfile.relay-test		Dockerfile.relay-test
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
cac		cac
cac-dns-guard.js		cac-dns-guard.js
cac.cmd		cac.cmd
cac.ps1		cac.ps1
install.sh		install.sh
package.json		package.json
test-docker.sh		test-docker.sh
test-real-guide.md		test-real-guide.md
test-relay-docker.sh		test-relay-docker.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

中文

简介

注意事项

安装

快速上手

版本管理

环境管理

全部命令

代理格式

隐私保护

工作原理

文件结构

Docker 容器模式

English

Overview

Notes

Install

Quick start

Version management

Environment management

All commands

Privacy protection

How it works

File layout

Docker mode

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

中文

简介

注意事项

安装

快速上手

版本管理

环境管理

全部命令

代理格式

隐私保护

工作原理

文件结构

Docker 容器模式

English

Overview

Notes

Install

Quick start

Version management

Environment management

All commands

Privacy protection

How it works

File layout

Docker mode

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages