Skip to main content

​
Overview

This page takes you from nothing to a working gateway in a few minutes:
  1. Run the gateway locally (Docker or npx).
  2. Point it at one provider by setting a single environment variable — no config file needed.
  3. Make your first /v1/chat/completions call.
  4. Open the web console.
The gateway is a single static binary (vikat-gateway) that listens on port 8080 by default and serves the API, the health endpoints, and the embedded web console from the same port.

​
Prerequisites

  • An API key for at least one auto-detected provider: OpenAI, Anthropic, or Mistral.
  • Docker, or Node.js 18+ (for the npx route — Linux only, see below).

​
Run the gateway

​
Option A: Docker

Run the published image, passing your provider key through:
The image’s entrypoint is the bare binary, so container args are process flags. The default command is:
/data is the app directory — where the gateway reads config.json (optional) and writes its config.db and logs.db. To keep configuration across restarts, mount a volume there (the container runs as uid 1000, so the directory must be writable by that user):
You can also build the image yourself. deploy/Dockerfile is the only image this repository builds, and because the Go modules use local replace directives, it must be built from the repo root:
Port, host, app directory, and log style are set only as flags (container args). The only settings the binary reads from the environment are LOG_LEVEL and VIKAT_HOST, which supply the defaults for -log-level and -host — there is no APP_PORT/APP_HOST/APP_DIR environment contract.

​
Option B: npx

The npm package (@vikat/vikat-gateway) downloads the release binary for your platform and verifies it against a SHA-256 digest pinned inside the package, then hands the process straight to the binary — arguments, Ctrl-C, and exit codes all pass through.
The gateway is a Linux server product: the npm package currently publishes a linux-amd64 binary only. On macOS or Windows, running vikat-gateway prints a note telling you to use Docker instead — use Option A there.

​
Flags

All runtime settings are command-line flags (transports/vikat-http/main.go): When -app-dir is not given, the gateway uses ~/.config/vikat on Linux/macOS and %APPDATA%\vikat on Windows. In the Docker image it is set to /data.

​
Point it at a provider

You do not need a config file to start. When the gateway boots with no providers configured — no providers in config.json and none stored from a previous run — it auto-detects these environment variables and configures the matching provider: Each detected provider is set up with that key, allowed for all models, and persisted to the config store. What is stored is a reference to the environment variable (env.OPENAI_API_KEY), not the key’s value — so the variable must stay set in the gateway’s environment on later starts too. You’ll see it in the startup logs:
Auto-detection only runs when nothing is configured yet. Once providers exist (from a config file, the web console, or a previous auto-detected run), it is skipped. For everything beyond the zero-config path — more providers, multiple keys, Azure/Bedrock/Vertex — see Provider Configuration.

​
Make your first request

The gateway exposes an OpenAI-compatible API. Prefix the model with the provider name (provider/model) to route the request:
The response comes back in OpenAI chat-completion format. Anthropic and Mistral work the same way once their keys are detected — "anthropic/claude-sonnet-4-5-20250929", "mistral/mistral-large-latest", and so on. To check the gateway is up without making a model call:
/health pings the gateway’s stores and returns 503 if any are unreachable (use it for readiness); /health/live answers only “is the process serving” and never consults a dependency (use it for liveness).

​
Open the web console

The web console is embedded in the binary and served at the root path:
From there you can add and edit providers and keys visually, watch live request logs, and manage governance (virtual keys, budgets, rate limits). Changes made in the console apply immediately. By default no authentication is configured — anyone who can reach the port can use the console and API. Before exposing the gateway beyond localhost, set up auth: see Setting Up Auth.

​
Next steps

Gateway setup in depth

Data persistence, flags, and the app directory in detail

Provider configuration

Multiple providers, key weights, and provider-specific settings

Streaming

Server-Sent Events streaming for chat completions

Drop-in integrations

Use existing OpenAI, Anthropic, or GenAI SDKs by changing only the base URL