llms.txt@docs git:20261101.e0698cfA

Immutable. This exact content never changes and is served at /api/v1/blob/fe6e79ba88f3d460.

# Cloakroom

> Free and open source. Cloakroom masks API keys, secrets and personal data on your own machine before your AI coding agent sees them. Works with Claude Code, Codex CLI, Gemini CLI and Cursor’s terminal agent.

## Pages

- [Home](https://cloakroom.sh/)
- [Install](https://cloakroom.sh/install.html)
- [Commands](https://cloakroom.sh/commands.html)
- [How it works](https://cloakroom.sh/how-it-works.html)
- [Security](https://cloakroom.sh/security.html)
- [Settings](https://cloakroom.sh/settings.html)
- [Releases](https://cloakroom.sh/releases.html)
- [Writing](https://cloakroom.sh/writing.html)
- [Source code](https://github.com/shanjeevrajendran/cloakroom)

<!-- https://cloakroom.sh/install.html -->
## Install Cloakroom
Works with Claude Code, Codex CLI, Gemini CLI and Cursor’s terminal agent.

#### Claude Code

Mac, Windows and Linux. You need Claude Code, installed and signed in.
- Add Cloakroom. Inside Claude Code, type these two lines, one at a time. If it asks where to install, pick the option for all your projects (user scope).

```
/plugin marketplace add shanjeevrajendran/cloakroom
/plugin install cloakroom@cloakroom
```

- Restart Claude Code. Type /exit, then claude again. Cloakroom now installs itself.
- Check it. Open a new terminal window and run:

```
cloakroom doctor       # see the example below
cloakroom dashboard    # opens your alerts in the browser
```

Example result:

```
ok   python: 3.14.7 on Darwin arm64
ok   version: cloakroom 1.1.0
ok   mode: full
ok   vault key: OS secure store
...   model: loading (the first run downloads it once, about 1 GB; that can take a minute or two)
ok   model: torch, loaded in 1.3 s, one check 17 ms (first check 704 ms, a one-time warm-up)
ok   service: up on port 37787, model loaded
warn  codex: not protected; to protect it: cloakroom install codex
warn  gemini: not protected; to protect it: cloakroom install gemini
warn  cursor: not protected; to protect it: cloakroom install cursor
ok   program: ~/.local/bin/cloakroom
```

Every line should say ok, except warn lines for agents you have not set up; each line says what to fix. The vault key line: the vault is Cloakroom’s encrypted file of the real values it hid, and “OS secure store” means its key sits in your system’s password store (Keychain on a Mac).

#### Codex CLI

Mac and Linux (tested with Codex 0.164).
- Install the program by hand.

```
uv tool install "cloakroom[model,torch,ocr]"
```

The part in brackets adds the AI model that finds names and addresses on your machine, and reading text in screenshots and scans.
- Run cloakroom install codex. It adds four hooks (small checks Codex runs before and after each action) to ~/.codex/hooks.json and leaves your own hooks alone.

```
cloakroom install codex
```

- Start Codex (codex), type /hooks, open each of the four Cloakroom hooks and trust it. Until you do, Codex skips them. cloakroom doctor shows whether they’re installed.

#### Gemini CLI

Mac and Linux (built against Gemini CLI 0.65).
- Install the program by hand.

```
uv tool install "cloakroom[model,torch,ocr]"
```

The part in brackets adds the AI model that finds names and addresses on your machine, and reading text in screenshots and scans.
- Run cloakroom install gemini. It writes one thing: a Gemini extension named cloakroom in ~/.gemini/extensions/cloakroom/. Your settings.json and your own hooks and extensions aren’t touched.

```
cloakroom install gemini
```

- Gemini runs the hooks (small checks before and after each action) from its next start, in every folder; gemini extensions list shows it, cloakroom doctor too.

#### Cursor

Cursor’s terminal agent (agent), not the editor. Mac and Linux.
- Install the program by hand.

```
uv tool install "cloakroom[model,torch,ocr]"
```

The part in brackets adds the AI model that finds names and addresses on your machine, and reading text in screenshots and scans.
- Run cloakroom install cursor. It adds nine hooks (small checks the agent runs before and after each action) to ~/.cursor/hooks.json and leaves your own hooks alone.

```
cloakroom install cursor
```

- Cursor’s terminal agent (agent) runs them from its next start. The editor reads the same file but hasn’t been checked with Cloakroom yet. cloakroom doctor shows whether they’re installed.

### Pick how you’ll run it
Easiest: add the plugin (above) and let it install Cloakroom on the next start. It uses uv or pipx if either is installed, otherwise a private Python environment in ~/.cloakroom/venv (needs Python 3.10+). If the install fails, Claude Code says so and it retries after 10 minutes. The table is for installing by hand.
| Your machine | Install | What you get
| Apple Silicon Mac, or an NVIDIA GPU | uv tool install "cloakroom[model,torch]" | Full mode (keys plus names and addresses) on the GPU, about 20 ms per check
| Any other machine (Intel Mac, most Windows and Linux) | uv tool install "cloakroom[model,torch]", then once: cloakroom export-onnx (saves a copy of the model that runs fast on a CPU) | Full mode on the CPU. Before the export it works but is slow (about 0.5 s per check); after it, about 60 ms on a modern CPU
| Just trying it, or a CI box | uv tool install cloakroom and CLOAKROOM_MODE=rules | Rules only: instant, no model download, but misses names and personal data in ordinary sentences
pipx install ... works the same way as uv tool install .... The model extras need about 1 GB of disk on a Mac and up to about 4 GB elsewhere (mostly PyTorch). Python 3.10 or newer.
To try it on one project first, install the plugin for that folder only. From inside the folder:

```
claude plugin marketplace add shanjeevrajendran/cloakroom --scope local
claude plugin install cloakroom@cloakroom --scope local
```

Other projects stay untouched.

### Using it outside Claude Code
The same engine works on any file or pipe, which is handy for checking what it would do:

```
cloakroom check config.py        # what would be masked, by kind; never prints the values
cloakroom explain config.py      # every finding with the rule that found it, and what was skipped as safe
cloakroom mask config.py         # the masked text, as the agent would see it
cat app.log | cloakroom check -  # read from stdin
cloakroom check --mode rules .env
```

Other commands: Commands.

### Headless machines, CI and testing

```
# just trying it, or a CI box: rules only, no model download
uv tool install cloakroom
CLOAKROOM_MODE=rules
```

- Vault key
The vault is Cloakroom’s encrypted file of the real values it hid. Its key lives in your system’s password store (Keychain, Credential Manager, Secret Service). On a machine without one, set CLOAKROOM_VAULT_KEY (a 256-bit key, base64 or 64 hex characters), or Cloakroom falls back to a key file readable only by you, and doctor says so.
- Dry run
CLOAKROOM_DRY_RUN=1 lets everything through and logs what Cloakroom would have done to ~/.cloakroom/dry-run.log. Useful for trying it on a real project before trusting it.
- Separate homes
CLOAKROOM_HOME moves the config, vault and model files; CLOAKROOM_PORT moves the local service (default 37787).

### If something looks wrong

#### cloakroom not found
Open a new terminal. The program lives in ~/.local/bin (on Windows, %USERPROFILE%\.local\bin); the installer adds that folder to your shell profile (~/.zshenv for zsh, ~/.bashrc and ~/.profile or ~/.bash_profile for bash) or, on Windows, to your user PATH.

#### Still setting up, or it failed
Progress, and numbered steps when something needs you, are written to ~/.cloakroom/bootstrap.log. More in Setup.

#### A Linux machine without curl
When neither uv nor pipx is there, Cloakroom fetches uv, which needs curl or wget. If a Linux machine has neither, Cloakroom tells you the steps: sudo apt install curl (Ubuntu/Debian) or sudo dnf install curl (Fedora/RHEL), then restart Claude Code.

#### Intel Mac
Only the pattern rules run, so keys, cards and ID numbers are caught but most names and addresses are not. The AI model for names and addresses needs PyTorch or ONNX Runtime, and neither is built for Intel Macs.

#### More fixes
Blocked prompts, ports, model: FAIL and too much masking: Settings and fixes.

<!-- https://cloakroom.sh/security.html -->
## Security model
What Cloakroom stores stays on your machine and is not sent anywhere. The values it hides are encrypted. Its job is to keep secrets and personal data away from the model, so a way around it is a security bug.
For auditors: vault files (the hidden values) are AES-GCM encrypted with a key in the OS secure store (your system’s password store, such as Keychain); the file log (~/.cloakroom/filelog.bin) is encrypted the same way; the activity log is tamper-evident, not tamper-proof: cloakroom report --verify spots a changed line, but someone who rewrites every later line can hide the change.

### What is stored
- The vault
Values go into the vault, an encrypted file kept per session.
- The file log
A record of where real values were put back into files the agent wrote. The log (~/.cloakroom/filelog.bin) is encrypted like the vault and holds no values: they are read back from the file when needed.
- Your rules
Rules you make from the dashboard are stored encrypted in ~/.cloakroom/rules.bin; the allow list stays yours to edit by hand.
- The activity log
Tamper-evident, not tamper-proof. The activity log keeps no values or text, but it does keep file paths (masked like any output) and the program name of shell commands.
- Held commands
Only a keyed hash of the held command is stored (~/.cloakroom/held.json): a fingerprint made with a secret key, not the command itself.
- Keys you hand over
Entries from cloakroom give expire after 24 hours; --forget removes one now.

### Where

#### The vault key
Vault files are AES-GCM encrypted; the key lives in the OS secure store (macOS Keychain, Windows Credential Manager, Linux Secret Service), or CLOAKROOM_VAULT_KEY, or a key file only you can read (permissions 0600) when no store exists (doctor warns).

#### Cloakroom’s own folder
The agent’s own tool calls can’t change ~/.cloakroom (writes there, or shell commands naming it, are denied), so it can’t pause Cloakroom or edit its rules.

#### The dashboard
The dashboard (cloakroom dashboard) is reachable only on 127.0.0.1, with a one-time sign-in link; restarting the service signs the browser out.

#### Claude Code’s own records
Claude Code’s local session log (~/.claude/projects/...) records the tool input after Cloakroom put the real values back, so those values also appear in that log on your disk. They are not sent to the model.

### What leaves your machine
- The model, once
First run downloads the AI model that finds names and addresses (PII-Tracer, at one fixed version) from Hugging Face; offline machines need it cached first.
- Sending data
Commands that would send a secret off your machine, or move money, wait for your OK. A web fetch, an MCP tool call (an add-on tool) or a prompt to a subagent that holds a real value is stopped before it runs.
- Not covered
Codex’s own web search (runs on OpenAI’s servers).

### What it cannot catch
It stops accidental exposure: secrets and personal data in files, logs and command output an agent reads while working. It is not a sandbox (a sealed-off space the AI can’t get out of). Out of scope: an AI, or hidden instructions in a file that steer it (a prompt injection), determined to sneak data out through custom encodings or values built piece by piece; data you paste into prompts on purpose (prompts can be blocked, not rewritten); what other tools on your machine send elsewhere.

#### Prompts
Prompts can only be blocked, not masked. A blocked prompt never reaches the model, but Claude Code keeps it in its local session records on disk.

#### Failed commands
In Claude Code, the error output of a tool call that fails goes through a hook event that lets a hook add notes but not change the text. So it can’t be masked and may reach the model with a key or personal value in it. Keep keys out of commands that print them.

#### Secrets it has never seen
Cloakroom looks for disguised copies (encoded or hashed) of values it already knows, so a secret it has never seen isn’t caught in any form. Not covered: salted or keyed hashes (HMAC, bcrypt, scrypt), other hashes (SHA-512, CRC), base32, upper/lower case changes of a key, and values shorter than 8 characters.

#### Keys written by scripts
A key split into pieces, or one with no known pattern and not seen earlier in the session, isn’t caught when a file is written.

#### Money moved by programs
The money-movement hold sees the command or tool call, not what a program does once it runs. A script or app that calls a payment API isn’t held.

#### The exposure list
cloakroom exposure lists only what Cloakroom detected: a key it missed leaves no line, so an empty list is not proof nothing leaked.
Every limit found in live tests, per agent: Known limits.

### Report a way around it
- Privately
Please report privately through GitHub: the Security tab of the repo, then Report a vulnerability. Don’t open a public issue for a bypass; it would teach everyone the trick before there’s a fix.
- What to include
The Cloakroom version (uv tool list or pip show cloakroom), your OS, the mode (full or rules), and a minimal example with fake values that shows the problem.
- Response
This is a one-person project. I aim to reply within a week and to ship a fix, with credit if you want it, before the details are public.
- Report a vulnerability
- SECURITY.md