> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vikat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the Vikat gateway locally, point it at a provider with one environment variable, and make your first OpenAI-compatible request.

## 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:

```bash theme={null}
docker run -p 8080:8080 -e OPENAI_API_KEY tarun026/vikat
```

The image's entrypoint is the bare binary, so container args are process flags. The default command is:

```bash theme={null}
vikat-gateway -app-dir /data -port 8080 -host 0.0.0.0
```

`/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):

```bash theme={null}
docker run -p 8080:8080 -e OPENAI_API_KEY \
  -v "$(pwd)/vikat-data:/data" tarun026/vikat
```

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:

```bash theme={null}
docker build -f deploy/Dockerfile -t vikat-gateway:latest .
docker run -p 8080:8080 -e OPENAI_API_KEY vikat-gateway:latest
```

<Note>
  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.
</Note>

### Option B: npx

```bash theme={null}
export OPENAI_API_KEY=sk-...
npx -y @vikat/vikat-gateway
```

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.

<Warning>
  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.
</Warning>

### Flags

All runtime settings are command-line flags (`transports/vikat-http/main.go`):

| Flag         | Default                              | Description                                           |
| ------------ | ------------------------------------ | ----------------------------------------------------- |
| `-port`      | `8080`                               | Port to run the server on                             |
| `-host`      | `localhost` (or `VIKAT_HOST` if set) | Host to bind to; use `0.0.0.0` in containers          |
| `-app-dir`   | OS config dir (see below)            | Data directory: `config.json`, `config.db`, `logs.db` |
| `-log-level` | `info` (or `LOG_LEVEL` if set)       | `debug`, `info`, `warn`, `error`                      |
| `-log-style` | `json`                               | `json` or `pretty`                                    |
| `-version`   | —                                    | Print the build version and commit, then exit         |

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:

| Provider  | Environment variables                |
| --------- | ------------------------------------ |
| OpenAI    | `OPENAI_API_KEY`, `OPENAI_KEY`       |
| Anthropic | `ANTHROPIC_API_KEY`, `ANTHROPIC_KEY` |
| Mistral   | `MISTRAL_API_KEY`, `MISTRAL_KEY`     |

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:

```text theme={null}
auto-detected openai provider from environment variable OPENAI_API_KEY
auto-configured 1 provider(s) from environment variables
```

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](/quickstart/gateway/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:

```bash theme={null}
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello, Vikat!"}]
  }'
```

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:

```bash theme={null}
curl http://localhost:8080/health
```

`/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:

```text theme={null}
http://localhost:8080
```

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](/quickstart/gateway/setting-up-auth).

## Next steps

<CardGroup cols={2}>
  <Card title="Gateway setup in depth" icon="server" href="/quickstart/gateway/setting-up">
    Data persistence, flags, and the app directory in detail
  </Card>

  <Card title="Provider configuration" icon="key" href="/quickstart/gateway/provider-configuration">
    Multiple providers, key weights, and provider-specific settings
  </Card>

  <Card title="Streaming" icon="bolt" href="/quickstart/gateway/streaming">
    Server-Sent Events streaming for chat completions
  </Card>

  <Card title="Drop-in integrations" icon="shuffle" href="/quickstart/gateway/integrations">
    Use existing OpenAI, Anthropic, or GenAI SDKs by changing only the base URL
  </Card>
</CardGroup>