From clone to first protected request.

You need Git and Docker with the Compose plugin. You also need an upstream provider credential to complete a live provider request, but it never belongs in the commands or examples below.

Git

Used to clone and update the public source repository.

Docker Engine

Runs the dashboard, management API, gateway, MCP server, worker, Postgres, and Redis.

Docker Compose

Use the current `docker compose` plugin form rather than the legacy standalone binary.

Provider credential

Add it later through the authenticated Provider Vault. Do not place it in shell history or a source file.

Gitea is the canonical source:

git clone https://git.cameronlow.com/cam/gatekyper.git
cd gatekyper

If GitHub is more convenient for discovery, clone the one-way mirror instead:

git clone https://github.com/gatekyper/gatekyper.git
cd gatekyper

Copy the documented template. It contains variable names and development defaults, not usable application secrets.

cp .env.example .env

Generate a separate random value for each of these required settings and place it in your local `.env` file:

• GATEKYPER_APP_SECRET
• GATEKYPER_TOKEN_HASH_PEPPER
• GATEKYPER_ENCRYPTION_KEY

The repository’s template documents this local generator:

node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64"))'

Run it three times. Do not reuse one value for multiple settings.

Use the full Compose profile; the default profile starts only the infrastructure dependencies used for local development.

docker compose --profile full up -d --build

Check that the services are running:

docker compose --profile full ps

The local dashboard is available at http://127.0.0.1:3000. The setup screen creates the first organization and owner account.

Use the authenticated dashboard to build the first boundary:

1. Create a project and an app or agent actor.
2. Add an OpenAI provider integration in Provider Vault.
3. Submit the real OpenAI credential through the vault form, test the candidate, and activate it.
4. Create a development policy that allows only the capability and model needed for the test.
5. Add a small daily budget and a short expiration.
6. Issue a test Gate Token and copy the display-once value to a temporary password manager entry or shell session.

Replace the clearly synthetic token below with the display-once test token you just issued. The example token is intentionally invalid and cannot authenticate.

export GATEKYPER_TOKEN='gk_test_demoPublicId1234_demoSecretValueNotValidReplaceBeforeUse12345'

curl --fail-with-body http://127.0.0.1:4100/v1/chat/completions \
  -H "Authorization: Bearer ${GATEKYPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Gatekyper-Provider: openai" \
  -H "X-Gatekyper-Task: getting-started" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Reply with: routed through Gatekyper"}],
    "max_tokens": 32
  }'

A successful gateway response includes an X-Gatekyper-Request-Id and a policy decision header. The Usage page records the request after it reaches the provider.

{
  "error": {
    "code": "gatekyper_policy_denied",
    "reason": "capability_not_allowed",
    "message": "This token is not allowed to use the requested capability.",
    "request_id": "gk_req_example"
  }
}

• Confirm that the successful request appears in Usage and the blocked attempt appears in Denials.
• Rotate the active provider credential and repeat the request with the same Gate Token.
• Revoke the Gate Token and confirm that its next request is denied.
• Review the corresponding administrative actions in Audit.

To stop the stack without deleting its volumes:

docker compose --profile full down

• Learn the core objects →
• Integrate a provider client →
• Connect an AI agent through MCP →
• Review the security model →