Quick Start

This page walks you through your first Redact-protected request from scratch: install Secret Guard, write a minimal config with one upstream Provider and one Secret to protect, start the gateway and send a request, then point your Agent tool’s base_url at it for daily use.

1. Install

The simplest path is grabbing a binary archive directly (fully static musl builds for Linux x86_64 / ARM64) — unpack and run. You can also install from the source repository (GitHub, MIT):

# Nix (flake):
nix run github:luochen1990/secret-guard -- --help
# Or wire up the overlay / nixosModule into your flake and use pkgs.secret-guard directly

# Cargo (builds from source, requires rustc >= 1.96):
cargo install --git https://github.com/luochen1990/secret-guard
# Or after cloning the repository: cargo install --path .

2. Minimal Configuration

Create secret-guard.toml in a directory of your choice (one upstream Provider + one Secret to protect is all it takes):

[[providers]]
id = "openai-main"
kind = "direct"                         # direct upstream (use "router" for a routing endpoint)
api_key = "sk-your-upstream-key"        # entry-level credential shared by all endpoints — must come BEFORE [[providers.endpoints]]
[[providers.endpoints]]
protocol = "openai"
base_url = "https://api.openai.com"

[[secrets.entries]]
id = "my-github-token"
value = "ghp_0123456789abcdefghijklmnopqrstuvwxyz"   # the secret to protect (never sent upstream)

Caution

Mind the nesting: Secrets live under [[secrets.entries]], while Providers are flat [[providers]] entries (the two styles differ, by historical design). Writing [[secrets]] instead causes a startup failure.

For every config section’s fields, types, and defaults, see the Configuration Reference.

3. Start and Send the First Request

secret-guard run --port 18787
curl http://127.0.0.1:18787/o/openai-main/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "My token is ghp_0123456789abcdefghijklmnopqrstuvwxyz, please summarize."
      }
    ]
  }'

The Secret in the request has been replaced by an equal-length realistic Mock Secret before reaching the upstream — the per-request log line’s redactions=1 is the replacement count, and the LLM never sees the real value.

Open http://127.0.0.1:18787/ in a browser and check the WebUI’s Records page to see this request from the LLM’s point of view (the Secret position is highlighted as a Mock). See the WebUI Guide for more.

Note

The examples in this guide use port 18787; without --port, the gateway listens on 127.0.0.1:8787 by default (you can also change it via [server] port or the SG_PORT environment variable).

4. Daily Usage via SDKs

For everyday use, simply point your Agent tool’s base_url at the gateway — no curl needed:

OpenAI Python SDK

from openai import OpenAI
client = OpenAI(
    base_url="http://127.0.0.1:18787/o/openai-main/v1",
    api_key="ignored",
)

Anthropic Python SDK

from anthropic import Anthropic
client = Anthropic(
    base_url="http://127.0.0.1:18787/a/anthropic-main",
    api_key="ignored",  # overridden by the provider config
)

Note

An SDK’s base_url must include the version path prefix itself (e.g. /v1); Secret Guard passes it through verbatim. The Anthropic SDK’s base_url likewise goes to /a/<provider-id> (that SDK appends /v1/messages itself).

5. URL Routing Conventions

URLs look like /{proto_short}/{provider_id}/*rest, encoding both the ingress protocol and the target Provider:

proto_short	Protocol	SDK example (base_url)
o	OpenAI	http://127.0.0.1:18787/o/<provider-id>/v1
a	Anthropic	http://127.0.0.1:18787/a/<provider-id>
g	Gemini	http://127.0.0.1:18787/g/<provider-id>
l	oLLama	http://127.0.0.1:18787/l/<provider-id>
r	Responses (OpenAI Responses API)	http://127.0.0.1:18787/r/<provider-id>/v1

Note: the URLs above are the SDK base_url form — the OpenAI SDK (Chat Completions and Responses share one SDK) needs the /v1 prefix included; the Anthropic SDK appends /v1/messages itself, so pointing it at /a/<provider-id> is enough; with plain curl, write the full path (see the example above).

6. Logs and Troubleshooting

Each completed forward logs a one-line INFO summary to stdout (forward method=... path=... status=... elapsed_ms=... redactions=N provider=...), so you can confirm traffic is flowing through Secret Guard without opening the WebUI. Upstream failures (502/504) return an error body with a readable cause (e.g. upstream error: http://127.0.0.1:29999 (Connection refused)). Under heavy volume, lower the verbosity with RUST_LOG=secret_guard=warn (default info).

For a symptom-to-fix table of configuration errors, see Configuration Reference — Common Configuration Errors.