Getting Started with Gatekeeper
Deploy Gatekeeper with Docker Compose, add your provider API keys, and make your first request to target models through a single endpoint — in under five minutes.
Prerequisites
- Docker and Docker Compose installed
- At least one AI provider API key (OpenAI, Anthropic, etc.)
- Port 4000 available (or configure a different port)
Deploy with Docker
Run the Docker container
The fastest way to start Gatekeeper is with a single Docker run command. This starts the proxy on port 4000 with an in-memory config — good for testing.
docker run -d \
-p 4000:4000 \
-e OPENAI_API_KEY=sk-... \
-e ANTHROPIC_API_KEY=sk-ant-... \
--name gatekeeper \
ghcr.io/gatekeeper-dev/gatekeeper:latestFor production, use Docker Compose with a PostgreSQL database for persistent config and usage data. See the self-hosting guide.
Verify the proxy is running
Check that Gatekeeper is up and can reach your configured providers:
curl http://localhost:4000/health
{
"status": "ok",
"providers": {
"openai": "reachable",
"anthropic": "reachable"
},
"version": "1.4.2"
}Add a virtual API key
Create a virtual key to hand to your application. This key routes to your real provider keys and can have budget limits, model restrictions, and usage tracking attached.
curl -X POST http://localhost:4000/v1/keys \
-H "Authorization: Bearer sk-gk-master-key" \
-H "Content-Type: application/json" \
-d '{
"name": "my-app",
"models": ["gpt-4o", "claude-3-5-sonnet-20241022"],
"budget_limit": 50.00,
"budget_period": "monthly"
}'{
"key": "sk-gk-myapp-xxxxxxxxxxxx",
"name": "my-app",
"budget_limit": 50.00,
"budget_remaining": 50.00,
"models": ["gpt-4o", "claude-3-5-sonnet-20241022"]
}Make your first request
Replace your OpenAI or Anthropic base URL with Gatekeeper's. Your existing SDK code works without any other changes.
from openai import OpenAI
client = OpenAI(
api_key="sk-gk-myapp-xxxxxxxxxxxx", # Your virtual key
base_url="http://localhost:4000/v1" # Point to Gatekeeper
)
response = client.chat.completions.create(
model="gpt-4o", # Or: "claude-3-5-sonnet-20241022"
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)curl http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer sk-gk-myapp-xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'Add to Your Blackhole Mesh
Use Gatekeeper via Blackhole CLI
If you have the Blackhole mesh installed, Gatekeeper can be validated as part of the Blackhole mesh onboarding path, with routing performance measured before claims are published.
# Chat through the mesh (routes to any node with an API key)
blackhole gatekeeper chat "Explain quantum computing"
# Add your provider key to the mesh
blackhole gatekeeper keys add openai sk-...
# Check usage and budget
blackhole gatekeeper usage