Self-hosted gateway quickstart

This quickstart is for EU-regulated platform and security teams that run Verdictan in their environment. Start with an empty working directory.

Then, create a gateway with a small reviewable policy chain. The gateway applies the chain to OpenAI-compatible Chat Completions traffic.

The gateway also records decision evidence. This is the measurable result for the supported rollout path.

This quickstart verifies the OpenAI-compatible Chat Completions path in a self-hosted or air-gapped environment. It demonstrates in-environment policy evaluation, provider-credential brokering, and request-level decision evidence. The console is not necessary.

Keep the first rollout in the supported boundary

Do not use this quickstart as availability evidence for these capabilities:

• Live MCP tool-action governance
• Hosted SaaS
• SSO and SCIM
• OAuth bearer access
• SIEM integrations
• Automatic model routing

Read Runtime Request Families before you make one of those capabilities a deployment requirement.

What you will do

1. Create a starter policy-config.yaml
2. Keep provider credentials out of YAML
3. Lint and test the config
4. Start the gateway
5. Send a governed Chat Completions request through the gateway
6. Verify its decision event before broader rollout

Using centrally managed BYOK routing?

If your organization manages provider keys in the control plane, follow Providers and BYOK Routing. This page also includes role bindings and resource tags.

Use that workflow to connect an agent to an authorized provider key.

Before you start

• Install verdictan with the instructions in Install the Gateway.
• Set VERDICTAN_API_URL to the URL of a reachable self-hosted Verdictan API.
• Export a gateway runtime token as VERDICTAN_API_TOKEN.
• Export a different application request token as VERDICTAN_REQUEST_TOKEN.
• Export one provider credential, such as VERDICTAN_OPENAI_API_KEY.

The active verdictan gateway run --policy-config flow binds local YAML to a registered agent through the control plane. A provider credential alone is not sufficient. The runtime and calling application must also authenticate. Keep the runtime and application tokens different.

Five-command path

The cURL path below uses five terminal commands after the prerequisites are in your environment:

1. verdictan init
2. lint and test the generated config
3. start the gateway
4. send one Chat Completions request
5. query the matching decision event

Run the gateway command in one terminal and the request and event commands in a second terminal. The Python and Node.js examples are alternatives to command 4, not more setup steps.

To verify the complete path, use an installed verdictan binary and a live provider. Complete the five command stages in this quickstart.

Make sure that the gateway records a matching decision event.

1. Create a starter config

verdictan init

Replace policy-config.yaml with a minimal config:

policy-config.yaml

pack:
  name: local-quickstart
  version: 0.1.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: your-model-id
      base_url: https://api.openai.com
      secret_key_ref:
        env: VERDICTAN_OPENAI_API_KEY

policies:
  chain:
    - prompt-injection
    - pii-detector
    - audit-logger

policy:
  pii-detector:
    action: redact

  audit-logger: {}

2. Keep secrets out of YAML

For a local gateway, export the provider credential in your shell:

export VERDICTAN_OPENAI_API_KEY="sk-..."

If you are using a centrally managed runtime, store the secret in Verdictan and reference it with secret_key_ref.store:

verdictan secret create \
  --name VERDICTAN_OPENAI_API_KEY \
  --env-var VERDICTAN_OPENAI_API_KEY

store-backed provider target

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: your-model-id
      base_url: https://api.openai.com
      secret_key_ref:
        store: VERDICTAN_OPENAI_API_KEY

The operator defines the environment-variable name. The gateway also resolves legacy names such as OPENAI_API_KEY.

We recommend Verdictan-prefixed names. These names identify the credential owner and the process that uses the credential.

3. Lint and test the config

verdictan policy lint --file policy-config.yaml && verdictan policy test --json

Add tests to the generated tests/ directory when you add policies to the chain.

4. Start the gateway

When you start the gateway from local YAML, give the CLI an agent binding and a runtime API token.

Export the prerequisite environment variables. Then, run this command:

verdictan gateway run \
  --agent quickstart-demo \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

VERDICTAN_API_TOKEN is for the runtime itself. Do not reuse it as the client credential for ordinary application requests.

5. Send your first request through the gateway

The gateway accepts the supported OpenAI request families. An OpenAI client can use it with a different base URL.

The client must also supply a Verdictan application token. Provider credentials stay in the gateway process.

Use the application request token from the prerequisites. If necessary, create one with verdictan token create --name quickstart-app --purpose general.

Store the one-time value in your secret manager. Export it as VERDICTAN_REQUEST_TOKEN before the five-command path.

Export the model ID that the gateway exposes before you run a client:

export VERDICTAN_GATEWAY_URL="http://127.0.0.1:41002/v1"
export VERDICTAN_REQUEST_TOKEN="vdt_..."
export VERDICTAN_MODEL="your-model-id"

cURL

curl http://localhost:41002/v1/chat/completions \
  -H "Authorization: Bearer ${VERDICTAN_REQUEST_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

Python

import os

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:41002/v1",
    api_key=os.environ["VERDICTAN_REQUEST_TOKEN"],
)

response = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:41002/v1",
  apiKey: process.env.VERDICTAN_REQUEST_TOKEN,
});

const response = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{role: "user", content: "Hello, world!"}],
});

console.log(response.choices[0].message.content);

Connected gateways must authenticate requests. The provider credential is used only for the upstream call and cannot replace the application token.

6. Verify the decision event

Query recent decision events. Make sure that the request, provider, model, and policy verdict from command 4 are shown:

verdictan events tail --since 10m --event-type decision --limit 20 --json

Also verify:

• The event output shows the matching request ID, policy verdict, provider, and model.
• The event timestamp follows the request that you sent.
• A request with a missing or invalid application token is rejected before an upstream provider call.

This verification path uses the CLI. The console is not necessary. Keep the request ID and event output as the evidence for the first governed request.

Next steps

• Config-First Workflow
• Configurations
• OpenAI Integration