pennameio/gateway repository overview

⁠penname gateway

Pseudonymize your customers' data before it reaches OpenAI or Anthropic — and restore it in the reply.

Set it up by hand, or let your AI coding agent (Claude Code, Codex, Cursor, Claude/ChatGPT desktop) do it through penname's built-in MCP server.

penname is an OpenAI/Anthropic-compatible proxy. On the way out it swaps real values — names, emails, phone numbers, ID numbers — for stable pen names like PERSON_7K3Q2M9XAB. On the way back it puts the real values in again. The model provider never sees the real thing. The gateway runs on your own machine and reads your database; nothing sensitive leaves your network. Nothing about your app changes except one base URL.

Website & dashboard: https://penname.io⁠

⁠What penname can and can't see

This is the whole point, so it's exact:

• The gateway runs on your machine. It reads your database and does the substituting. It is the only thing that ever touches a row. It holds your master key. Neither the master key nor any row ever leaves it.
• penname's hosted side (the dashboard + MCP) receives only: your table and column names and types, the relationships between them, which columns you marked sensitive, and token counts for usage. Never a row, never a name, never a prompt, never your master key.
• Your provider key is forwarded untouched. penname never stores your OpenAI/Anthropic key — your app keeps sending it and the gateway passes it straight through.
• You can run it fully offline. Leave PENNAME_CONTROL_PLANE_URL unset and the gateway talks to nothing but your own database and your own model provider — no calls to penname at all.

⁠Install

1. Get a key (free, no payment) — sign up at https://penname.io/signup⁠ and copy your pk_….

2. Run the gateway in a new folder. Docker is the only thing you install:

docker run -it -v ${PWD}/penname:/setup pennameio/gateway init
cd penname && docker compose up -d

init asks for your key and (optionally) a read-only database URL, generates your master key, and writes .env, secrets.env and docker-compose.yml for you.

3. Point your model client at it — keep your provider API key exactly as-is:

# OpenAI-compatible
client = OpenAI(base_url="http://localhost:8088/v1", api_key=YOUR_OPENAI_KEY,
                default_headers={"X-Penname-Scope": f"user={user_id}"})
# Anthropic
client = Anthropic(base_url="http://localhost:8088", api_key=YOUR_ANTHROPIC_KEY)

The X-Penname-Scope header tells the gateway whose records a request is about — without it, names reach the model in the clear (emails and phones are still protected, because they have a shape; names do not). Run curl localhost:8088/scope for the exact keys from your schema.

⁠Set it up from your AI agent (MCP)

penname runs an MCP server, so your coding agent can do the whole thing — read your schema, mark what's sensitive, and troubleshoot. The signup page hands you a ready prompt with your key in it, or add the MCP directly:

claude mcp add --transport http penname https://penname.io/mcp \
  --header "Authorization: Bearer pk_your_key"

⁠Ports

⁠Environment variables

init sets all of these for you — you normally never touch them by hand.

⁠Tags

• latest, 0.1.4 — current, multi-arch (linux/amd64 + linux/arm64)
• Version tags (0.1.x) are immutable — pin one in production.

⁠Learn more

Dashboard, usage, and managing what's sensitive: https://penname.io⁠

Proprietary. © penname.