Gateway Quickstart

0Get Your Credentials 5 min Compliance / Admin

Sign up to create your account. You'll receive four credentials — two API keys and two registry credentials:

Send IT the Gateway Key, Registry Username, and Registry Token via a secure channel, along with this page. The Account Key is generated later in Step 5.

1Install Liberty 1 min IT / DevOps

Liberty is our free, open-source secrets manager. It encrypts your keys to your hardware fingerprint — no .env files, no plaintext, no leaks. The gateway CLI reads from Liberty automatically.

pipx install liberty-secrets
liberty init
# pipx not installed? Use: pip install --break-system-packages liberty-secrets

2Log In and Pull Images 1 min IT / DevOps

LockStock images are hosted on a private GitLab Container Registry. Store the registry credentials from your welcome email (Step 0) in Liberty, then authenticate Docker:

# Store registry credentials in Liberty (one-time)
liberty add LOCKSTOCK_REGISTRY_USER "deploy-XXXXXXXX"
liberty add LOCKSTOCK_REGISTRY_TOKEN "gldt-XXXX..."

# Authenticate Docker from Liberty (no plaintext passwords)
liberty show LOCKSTOCK_REGISTRY_TOKEN | docker login registry.gitlab.com \
  -u "$(liberty show LOCKSTOCK_REGISTRY_USER)" --password-stdin

# Gateway (production middleware — runs as a service)
docker pull registry.gitlab.com/d3cipher/lockstock-images/gateway:v4.19.2

# Admin-Tools (compliance CLI — run on-demand)
docker pull registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2

3Install the Gateway CLI 1 min IT / DevOps

The lockstock-gateway CLI is a bash script inside the admin-tools image you pulled in Step 2. Extract it to your host:

mkdir -p ~/.local/bin
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  cat /usr/local/bin/lockstock-gateway > ~/.local/bin/lockstock-gateway && \
  chmod +x ~/.local/bin/lockstock-gateway

Verify it works: lockstock-gateway --help
Command not found? Run: export PATH="$HOME/.local/bin:$PATH" (add to ~/.bashrc or ~/.zshrc to make permanent)

4Store Your Keys in Liberty 2 min IT / DevOps

# Required — the gateway will not start without these
liberty add LOCKSTOCK_API_KEY "lsk_admin_..."
liberty add LOCKSTOCK_GATEWAY_KEY "lsk_gateway_..."
liberty add LOCKSTOCK_UPSTREAM_URL "https://api.openai.com"

# Set LOCKSTOCK_UPSTREAM_URL to your AI provider's endpoint:
#   https://api.openai.com        OpenAI
#   https://api.anthropic.com     Anthropic
#   http://localhost:11434         Ollama / local models

# Store your AI provider key (whichever you use)
liberty add ANTHROPIC_API_KEY "sk-ant-..."
liberty add OPENAI_API_KEY "sk-..."

Verify: lockstock-gateway config — all required fields should show values, not MISSING. From now on, every lockstock-gateway command reads from the vault automatically.

5Generate & Store Your Account Key 2 min Compliance / Admin + IT

Open the dashboard → Settings → Generate Account Key.

Send the Account Key to IT via a secure channel, then store it:

liberty add LOCKSTOCK_ACCOUNT_KEY "your-64-char-hex-key"

Without the Account Key, your gateway still runs — the audit chain records every action and the kill switch works. But transcript content will not be encrypted, and the Auditor tab in your dashboard will show "Blob not available" for all transcripts. You can add the Account Key later and restart the gateway.

6Register an Agent 2 min IT / DevOps

Register at least one agent before starting the gateway. Choose one path:

# Option A: Provision from the CLI (recommended — one command, fully automatic)
lockstock-gateway provision --name my-agent

# The CLI auto-detects your provider from Liberty. Override with:
# lockstock-gateway provision --name my-agent --provider anthropic-native

# Option B: Provision from the dashboard, then activate locally
#   1. Go to dashboard > Provision Agent > copy Agent ID and Genesis Token
#   2. Run:
lockstock-gateway activate \
  --agent "agent_XXXXXXXX_my_agent" \
  --token "your-genesis-token" \
  --name my-agent

# --name sets the Liberty key label (e.g., LOCKSTOCK_AGENT_MY_AGENT).
# If omitted, derived from the agent ID.

# Verify your registered agents
lockstock-gateway agents

7Start the Gateway 1 min IT / DevOps

lockstock-gateway start

Verify it's running:

curl http://localhost:4000/healthz
# {"status": "ok", "version": "4.6.2"}

To stop: lockstock-gateway stop • Full status (container + agents + config): lockstock-gateway status

These are the container-side variable names, used in Docker Compose and Kubernetes manifests. If you use lockstock-gateway start with Liberty, store them with the LOCKSTOCK_ prefix (e.g., LOCKSTOCK_UPSTREAM_URL). The CLI maps them automatically.

8Point Your Agents at the Gateway 5 min IT / DevOps

Change your AI client's base URL to route through the gateway instead of directly to the provider:

# OpenAI SDK / OpenAI-compatible
OPENAI_BASE_URL=http://localhost:4000

# Anthropic SDK / Claude Code
ANTHROPIC_BASE_URL=http://localhost:4000

Single agent

That's it. The CLI auto-sets the default agent identity when exactly one agent is registered — no header needed. Just change the base URL and go.

Multiple agents

Each client identifies itself to the gateway with the X-D3cipher-Agent header. The value is the agent ID from Liberty — the agent_XXXXXXXX_my_agent format written by lockstock-gateway provision or activate in Step 6. You can retrieve it with:

liberty show LOCKSTOCK_AGENT_MY_AGENT
# → agent_a3f7b2c1_my_agent

How you set that header depends on which SDK your agent uses:

# ── Claude Code ──────────────────────────────────────────────
# Set ANTHROPIC_CUSTOM_HEADERS before launching Claude Code.
# The SDK sends these headers on every API request.
# Docs: https://docs.anthropic.com/en/docs/build-with-claude/claude-code

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=$(liberty show ANTHROPIC_API_KEY)
export ANTHROPIC_CUSTOM_HEADERS="X-D3cipher-Agent: $(liberty show LOCKSTOCK_AGENT_MY_AGENT)"
claude

# ── OpenAI Python SDK ────────────────────────────────────────
# Pass the header via default_headers on the client constructor.
# Docs: https://github.com/openai/openai-python#custom-headers

import openai
client = openai.OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="sk-...",  # your OpenAI key
    default_headers={
        "X-D3cipher-Agent": "agent_a3f7b2c1_my_agent"  # from Liberty
    }
)

# ── OpenAI Node.js SDK ───────────────────────────────────────
# Docs: https://github.com/openai/openai-node#custom-headers

const client = new OpenAI({
    baseURL: "http://localhost:4000/v1",
    apiKey: "sk-...",
    defaultHeaders: {
        "X-D3cipher-Agent": "agent_a3f7b2c1_my_agent"  // from Liberty
    }
});

# ── curl ─────────────────────────────────────────────────────
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "X-D3cipher-Agent: $(liberty show LOCKSTOCK_AGENT_MY_AGENT)" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"hello"}]}'