llms.txt@docs · git:20261031.ae72e3d · 2026-10-31 · sha256 7a85eb462923ad79
llms.txt@docs git:20261031.ae72e3dA
Immutable. This exact content never changes and is served at /api/v1/blob/7a85eb462923ad79.
# 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 and Gemini CLI. ## 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) - [Releases](https://cloakroom.sh/releases.html) - [Writing](https://cloakroom.sh/writing.html) - [Settings and fixes](https://cloakroom.sh/settings.html) - [Source code](https://github.com/shanjeevrajendran/cloakroom) <!-- https://cloakroom.sh/install.html --> ## Install Cloakroom Works with Claude Code, Codex CLI and Gemini CLI. #### 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 # every line should say ok cloakroom dashboard # opens your alerts in the browser ``` #### Codex CLI Mac and Linux (tested with Codex 0.164). - Install the program by hand. ``` uv tool install "cloakroom[model,torch,ocr]" ``` - Run cloakroom install codex. It adds four hooks 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]" ``` - 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 from its next start, in every folder; gemini extensions list shows it, cloakroom doctor too. ### 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 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 | 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 free-text personal data 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 Claude 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 key lives in the OS secure 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 detection 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 Cloakroom’s job is to keep secrets and personal data away from the model, so a way around it is a security bug. ### What is stored - The vault Values go into the vault, an encrypted file kept per session (AES-GCM, key in the OS secure store). - The file log 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 These rules 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). - 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 0600 key file when no store exists (doctor warns). #### Cloakroom’s own folder Claude’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 hook’s rewritten tool input, so values put back into a file 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 detection model (PII-Tracer, pinned revision) 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 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 Disguised copies are computed from values Cloakroom 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