Quickstart

Zero to a protected agent

About five minutes. At the end, your agent can read repositories and comment on pull requests through a token that is worthless outside the proxy — and cannot touch anything you did not grant.

1. Install

curl -fsSL https://grenz.dev/install.sh | sh

Or run it in Docker. Bind to loopback explicitly — publishing the port without a host exposes the proxy to your whole network:

docker run -p 127.0.0.1:8787:8787 -v ~/.grenz:/root/.grenz ghcr.io/grenz/grenz run

2. Scaffold a home

grenz init

This creates an age identity, an encrypted vault, a starter grenz.yaml and policy.yaml, and mints your first GRENZ_TOKEN. The token is printed once — copy it now. If you lose it, grenz rotate <agent> issues a new one.

3. Store the real credential

printf %s "$GITHUB_TOKEN" | grenz vault set github_token

The value is read from stdin so it never lands in your shell history. From here on it lives in the age-encrypted vault and is decrypted only inside the proxy.

4. Write the policy

Edit ~/.grenz/policy.yaml. Grant the narrowest thing that lets the agent do its job:

agent: claude-code
on_behalf_of: you@example.com
grants:
  - tool: github
    allow: [repo:read, pr:comment]
    require_approval: [pr:create]
    deny: [repo:delete, actions:*]

Check it before you rely on it. grenz policy check validates and summarizes; grenz policy lint flags dead patterns and grants broader than they look.

5. Run it

grenz run

Not sure the setup is sound? grenz doctor checks config, vault, policy, credentials, and port availability offline, and exits non-zero on anything broken — so grenz doctor && grenz run gates startup.

6. Point the agent at it

Two things change in the agent's configuration: the base URL, and the token.

GITHUB_API_URL=http://127.0.0.1:8787/u/github
GITHUB_TOKEN=cav_…  # the GRENZ_TOKEN, not your real one

That is the whole integration. The agent speaks ordinary HTTP to what looks like the GitHub API; Grenz matches each request against your policy, swaps in the real credential only for what it allows, and forwards it.

Try the guardrails

Ask the agent to do something you denied. You should see it refused, with a reason:

Then ask it to open a pull request. The request blocks in-flight and waits for you — approve it with grenz approve <id>, or let it expire and be denied.

Next

• Wrap an MCP server — the same flow for Linear, Slack, or anything else speaking MCP.
• Policy format — budgets, schedules, approval memory, delegation.
• Security model — what the boundary actually covers.