Getting started
Run dgateway with its built-in mock, then connect your own providers.
This guide starts dgateway, sends a first decision to its built-in mock and then connects real models. The mock needs no API key.
Run the image
Start the container. Before you use it beyond a local trial, replace the ADMIN_TOKEN and GATEWAY_SECRET values with two different long random strings. Keep GATEWAY_SECRET the same over time: it encrypts the provider keys you store.
docker run -d --name dgateway \
-p 127.0.0.1:8790:8790 \
-v dgateway-data:/data \
--add-host host.docker.internal:host-gateway \
-e ADMIN_TOKEN=replace-with-a-long-random-token \
-e GATEWAY_SECRET=replace-with-a-separate-stable-secret \
ghcr.io/buddylabsai/dgateway:latestInside a container, localhost is the container itself. The --add-host line lets a container on Linux reach your machine as host.docker.internal, for example to call a model server there; Docker Desktop has this name already.
To connect real models, open the console at http://127.0.0.1:8790/ and sign in with the admin token. On Providers, add or configure a provider, run Test with your chosen model, and turn the provider on. On Models, create a route with a step for that provider and model. Send the route name in your request's model field. Calls to /v1/decisions need no key until you turn on client keys in settings. Provider setup and compatibility
Your app names a route in the model field, and the route decides which models answer. A new install has a test route named default. It answers with a built-in mock instead of a real model, so you need no API key.
The mock does not read the text. It takes its numbers from a hash of the input, so it shows the response format, not model quality.
Ask it three questions about a support ticket in one request:
curl http://127.0.0.1:8790/v1/decisions \
-H 'Content-Type: application/json' \
-d '{
"model": "default",
"input": "I got charged twice for my March invoice. Please refund the extra charge.",
"questions": [
{
"name": "team",
"type": "choice",
"instructions": "Which team should handle this ticket?",
"choices": [
{"value": "billing", "description": "Invoices, charges and refunds"},
{"value": "technical", "description": "Bugs, errors and outages"},
{"value": "account", "description": "Login, profile and access"}
]
},
{
"name": "refund",
"type": "predicate",
"instructions": "Does the customer ask for a refund?"
},
{
"name": "urgency",
"type": "score",
"instructions": "How urgent is this ticket?",
"levels": [
{"label": "low", "description": "Can wait a few days"},
{"label": "normal", "description": "Answer today"},
{"label": "high", "description": "Answer within the hour"}
]
}
]
}'Actual mock response (ID, time and latencies vary)
{
"id": "dec_f533293c7410efb6332b5f81",
"object": "decision",
"created": 1794435452,
"model": "default",
"answers": [
{
"type": "choice",
"name": "team",
"choice": "billing",
"probabilities": [
{ "value": "billing", "probability": 0.4039408866995074 },
{ "value": "technical", "probability": 0.3760262725779967 },
{ "value": "account", "probability": 0.2200328407224959 }
],
"confidence": 0.027914614121510695,
"confidence_method": "upstream"
},
{
"type": "predicate",
"name": "refund",
"probability": 0.8941176470588236
},
{
"type": "score",
"name": "urgency",
"score": 0.870722433460076,
"probabilities": [
{ "value": 0, "label": "low", "probability": 0.5095057034220533 },
{ "value": 1, "label": "normal", "probability": 0.11026615969581749 },
{ "value": 2, "label": "high", "probability": 0.38022813688212925 }
],
"confidence": 0.129277566539924,
"confidence_method": "upstream"
}
],
"usage": { "input_tokens": 76, "output_tokens": 3, "total_tokens": 79 },
"gateway": {
"route": "default",
"provider": "mock",
"upstream_model": "mock-1",
"served_by": "Mock",
"upstream_model_resolved": "mock-1",
"synthetic": false,
"latency_ms": 3,
"attempts": [{ "provider": "mock", "model": "mock-1", "ok": true, "latency_ms": 3 }],
"confidence_method": "upstream",
"cost_usd": 0,
"cost_basis": "upstream_cost",
"cost_includes_output": true,
"tokens": 76
}
}How to read it:
choiceis the most likely team.probabilitiesgives the probability of each team.- The yes/no question returns
probability, the chance that the answer is yes. scoreis the expected level: 0 is low and 2 is high. It is the sum of each level number times its probability.gatewaynames the provider and model that answered, lists each attempt and gives the cost in US dollars.
Run with Docker Compose
From a checkout of this repository, copy the example settings:
cp .env.example .envSet ADMIN_TOKEN and GATEWAY_SECRET in .env, as in Run the image. You can also set provider API keys there; see providers. Then start it:
docker compose up -dCompose uses the published image, binds port 8790 to localhost and keeps data in the dgateway_gateway-data volume. docker compose up -d --build builds the image locally. docker compose down -v deletes the volume. GET /healthz needs no token.
Run from source
Install Bun 1.3. From the repository root:
bun install
ADMIN_TOKEN=replace-with-a-long-random-token GATEWAY_SECRET=replace-with-a-separate-stable-secret bun run startThe API runs right away on 0.0.0.0:8790. Set DGATEWAY_HOST or DGATEWAY_PORT to change it. Data goes to ./data; set DATA_DIR to change it.
The Docker image includes the admin console. From source, build it once:
cd src/modules/gateway/apps/console-web
bun install
bun run buildUntil you build it, http://127.0.0.1:8790/ shows a placeholder page. The API works either way. The server looks for the built console in the console's dist directory; set CONSOLE_DIR to use another one.
Connect your own providers
Open the console, add and test a provider, then create a route with a step for each provider you want it to try. Try these next:
- Routes and fallback: your app keeps one route name while you change the providers behind it. A route can also stay on your own machine.
- Cost: what each decision cost and where the number came from: billed, token-priced, estimated or unpriced. dgateway shows spending; it does not stop spending at a budget.
- Providers: hosted vendors and model servers on your own machine.
- Security: stored provider keys are encrypted, and payload capture is off by default.
- Decision API: every field, with tested examples.
- Synthetic decisions: how chat models answer decision questions.
confidence is not proof that an answer is right. Test your provider, model, instructions and thresholds on examples you have labelled yourself before you rely on them.
A new install has three routes: default, luna and elephant. It also has the llamacpp, typesafe, openai-chat and openrouter-chat providers, turned off. openai-chat and openrouter-chat call chat models to answer decision questions.
dgateway has no chat-completions endpoint and does not choose the best model for a task. See all limits.