Install

New to Pentect? Choose your OS and install method. The installation page covers Windows, macOS, Linux, npm, Homebrew, APT, AUR, and Nix.

Already installed? Continue below. You do not need to change the permanent settings of Codex or Claude.

Start a protected session

1. Check Pentect and the client.

   pentect doctor

2. Launch the client through Pentect.

   pentect codex
   # or
   pentect claude

3. Work normally in the client that opens.

   Start with a local test file containing a fake credential. For detected values, the model receives a handle such as <<DATABASE_URL_4ce8a3b0a6f64e12>> instead of the original text.

   When the agent needs the value, it copies the complete handle into a shell, file, connector, or MCP tool argument. Pentect validates the completed local tool call before restoring known handles. See Handles for the boundary and lifetime rules.

4. Watch local protection events when you need to verify a flow.

   pentect log --once --tail 100

What success looks like

You can test the request boundary with fake data. Paste this into the protected client:

Remember OPENAI_API_KEY=sk-ABCDEFGHIJKLMNOPQRSTUVWX for this task.

The provider-bound prompt contains an <<OPENAI_API_KEY_...>> handle instead of the fake value. The same protection applies to supported text returned by a terminal, file tool, browser, or MCP server.

If a file contains DATABASE_URL=postgres://..., the provider sees a handle instead of the credential:

DATABASE_URL=<<DATABASE_URL_4ce8a3b0a6f64e12>>

The agent can copy the handle into a local tool call. Pentect restores it just before the tool runs. Pentect then masks sensitive command output before it returns to the provider. pentect log records the event and label, not the real value.

If a command prints the value and the result contains the handle again, that is expected. The command received the value locally, and Pentect protected the output before the next provider request.

The client should still stream responses, run tools, and accept its normal flags. If a request format cannot be checked, Pentect returns an error instead of sending it by default.

Normal client arguments pass through unchanged:

pentect codex exec --full-auto
pentect claude --model sonnet

The same launch pattern works for other supported clients. The complete, release-tested matrix is on the Compatibility page:

Client	Command
OpenCode	pentect opencode
Pi	pentect pi

Each command protects a specific surface. Check the client page before you use desktop, autocomplete, or external-agent features.

Other client pages are status pages only. They are listed under Not implemented, and their proposed commands do not work in the current release.

Use Pentect from your normal CLI command

This step is optional. If you want codex or claude to use Pentect without typing the pentect prefix, run:

pentect codex --set-default
pentect claude --set-default

Pentect detects PowerShell, Bash, Zsh, or Fish. Before changing anything, it shows the profile path and the function it will add. It also backs up an existing profile. Restart the terminal after you approve the change.

After that, launch either client as usual:

codex exec --full-auto
claude --model sonnet

Remove only the profile block created by Pentect with:

pentect codex --unset-default
pentect claude --unset-default

Add a clickable App launcher

This is also optional. Add a separate protected launcher for the desktop App:

pentect codex app --install-launcher
pentect claude app --install-launcher

System	Launcher location
Windows	Start menu → Pentect
macOS	~/Applications

Pin Codex via Pentect or Claude via Pentect to the taskbar or Dock. The launcher starts the same local Pentect gateway as the terminal command, without leaving a terminal window open. The official App and its shortcut are not changed.

The Codex launcher forcibly restarts an already-running Codex App so it can inherit the temporary Pentect routing; save your input and finish active tasks first. For Claude Desktop, quit the official App before using its protected launcher.

Remove the launcher with:

pentect codex app --remove-launcher
pentect claude app --remove-launcher

The remove command checks that Pentect created the launcher. It will not delete an unrelated shortcut or App with the same name.

Try masking without an agent

cat .env | pentect mask
cat terraform.tfvars | pentect mask

PowerShell:

Get-Content .env -Raw | pentect mask

The output contains reusable handles. Pentect does not print the real values.

TIP

The default is optional. It affects only supported clients started from that shell; it does not create a proxy for the whole system.

Next steps

• Open the client page from the sidebar for exact protected and unsupported surfaces.
• See Structured data for dotenv, Terraform, Kubernetes, and JSON behavior.
• Read Handles before copying handles between sessions or scripts.
• Review Files and images before sending uploads.
• See Prompts and tool results for pasted secrets, accidental output, MCP browsers, and screenshots.
• Run pentect doctor again after changing a client installation or provider.
• Copy a complete task from Examples.