OpenViking Gateway deployment and operations

This page is for the people who run OpenViking Gateway as a service: deploy it in the form that suits you, put it behind a proxy, control who can change it, and keep it healthy through upgrades and migrations. You need an OpenViking Server that uses API-key authentication or local dev mode; the full list is under Requirements. If you are new to the gateway, read OpenViking Gateway first.

Note: The gateway is in beta. Settings and APIs may change between releases, so read the release notes before you upgrade.

Looking for something else? This page covers running the gateway. For everything else:

• Studio tabs and settings: Manage OpenViking Gateway in Studio, then Upstreams, Context profiles, Gateway keys and Gateway overview and request log.
• An error, a warning or a Studio setup card: Troubleshoot OpenViking Gateway.
• A configuration field or environment variable: Configuration reference.
• What is stored, who can see it, retention and backups: Security and data.
• OpenViking tools or long conversations: OpenViking tools in the gateway and Long conversations in the gateway.
• Settings for one client: Connect clients.

Requirements

Requirement	Details
OpenViking authentication	api_key or local dev mode. The gateway does not support trusted authentication.
OpenViking version	An embedded gateway ships with the server, so there is nothing to check. A standalone gateway needs OpenViking Server 0.4.16 or later.
Installation	The gateway is part of the OpenViking core package. The optional gateway-fast extra (pip install "openviking[gateway-fast]") adds a faster event loop and HTTP parser.
Sign-in	Remote deployments need an OpenViking API key; users, account admins and root can all sign in to the gateway pages in Studio. Local dev mode needs no key and always uses the default/default identity.
Storage	A local disk. The gateway's SQLite databases serve one host only; network filesystems and storage shared between hosts are not supported.

Choose a deployment form

The gateway runs either inside the OpenViking Server (embedded) or as its own process (standalone). Both serve the same model and management paths under /gateway.

Form	Choose it when	How to enable it	Client address
Embedded in the server (including Compose and Helm)	You run the OpenViking Server yourself. There is no second process and no path-based reverse proxy.	Turn on gateway.enabled in ov.conf	The server address plus /gateway, http://127.0.0.1:1933/gateway by default
Standalone	You want to leave the OpenViking service's configuration untouched, for example an OpenViking Cloud service.	openviking-gateway init, then openviking-gateway	The gateway's own address plus /gateway, http://127.0.0.1:1935/gateway by default

Then follow the section for your setup: Enable it in the server, Docker Compose, Helm or Standalone deployment.

Enable it in the server

The embedded gateway runs inside the OpenViking Server on the same port, and it is off by default (gateway.enabled is false). Until you turn it on, Studio's OpenViking Gateway page shows The gateway is not enabled on this OpenViking server. Turn it on in one of three ways.

With openviking-server init. Answer yes to Enable OpenViking Gateway on the same port?, then start or restart the server. With an existing configuration, choose Update gateway from the menu. For a remote deployment, init also asks whether users may configure upstreams themselves; see Gateway management key.

In ov.conf. Merge this into ov.conf and restart the server:

{
  "gateway": {
    "enabled": true
  }
}

From Studio. On a server that uses API keys, root can choose Enable gateway on Studio's OpenViking Gateway page. Studio writes gateway.enabled: true to ov.conf and restarts the server. The confirmation dialog can also generate a gateway management key; see Gateway management key. Exceptions:

• Restarting from Studio needs a single-worker server. Otherwise Studio only saves the file, and you restart the server yourself.
• When OPENVIKING_GATEWAY_ENABLED is set, it overrides gateway.enabled in ov.conf, so a false value keeps the gateway off after the restart.
• If ov.conf is read-only, for example mounted from a Helm ConfigMap, Studio cannot change it. Set gateway.enabled: true in the Helm values or OPENVIKING_GATEWAY_ENABLED=true, then restart the server.

Check that it is on. Open /studio/ on the server and choose OpenViking Gateway in the sidebar: you should see the gateway tabs instead of the not-enabled card. In local dev mode, if the default account has no upstreams, the gateway imports the server's usable VLM credentials as upstreams at startup and creates a default context profile. Imported Coding Plan upstreams need confirmation before use; if nothing can be imported, add an upstream by hand (Upstreams).

Letting an agent change the configuration. An agent that holds the root API key can edit ov.conf and restart the server through the runtime configuration API. A standalone gateway does not offer this API.

Docker Compose

With Docker Compose, the gateway runs inside the openviking service; there is no separate service or profile.

1. Set OPENVIKING_GATEWAY_ENABLED=true in .env, or turn on gateway.enabled in the mounted ov.conf. When the variable is set, it wins over ov.conf.
2. Make sure the mounted ov.conf uses API-key authentication: the server listens on 0.0.0.0 inside the container.
3. Run docker compose up -d, open /studio/ on port 1933 and choose OpenViking Gateway. You should see the gateway tabs; if the server does not come up, read the startup errors with docker compose logs openviking.

Without Compose, add -e OPENVIKING_GATEWAY_ENABLED=true to docker run:

docker run -d -p 1933:1933 -v ~/.openviking:/app/.openviking \
  -e OPENVIKING_GATEWAY_ENABLED=true \
  ghcr.io/volcengine/openviking:latest

• Management key: set OPENVIKING_GATEWAY_MANAGEMENT_KEY in .env, and the bundled Compose file passes it into the container; or put it in gateway.management_key in the mounted ov.conf. The Compose file also passes OPENVIKING_GATEWAY_ENCRYPTION_KEY, which is only read once to migrate v0.5 data; see Migration.
• Public address: set OPENVIKING_PUBLIC_BASE_URL (the bundled Compose file passes it); the gateway uses it when it has no public_url of its own. See Public address.
• After a configuration change: after editing the mounted ov.conf, run docker compose restart openviking. After editing .env, run docker compose up -d: restart reuses the existing container and does not pick up new .env values.

The bundled Caddy forwards all paths to openviking:1933. Clients can keep using the compatibility port 1934, or go straight to the server on 1933. For HTTPS, a single reverse_proxy openviking:1933 carries Studio, the management API and model traffic; see Public access.

Helm

With the Helm chart, set gateway.enabled: true in the chart values. The gateway runs inside the server container, keeps its data in <persistence.mountPath>/gateway, and uses the server port for both the Service and the Ingress. Keep replicaCount: 1.

gateway:
  enabled: true
  existingSecret: ""  # optional: Secret name, entry management-key
config:
  gateway:
    public_url: https://ov.example.com

• The gateway encrypts its data with the chart's config.encryption settings, the same as the server.
• With a management-key entry in the existingSecret Secret, changing upstreams and context profiles requires that management key.
• Model requests stream: the Ingress must turn off response buffering and allow request bodies of at least 32 MiB and timeouts of 600 seconds (see Reverse proxy and HTTPS).

The NGINX annotations, the commands to create the Secrets and the notes on upgrading from the sidecar chart are in the chart README.

Standalone deployment

A standalone gateway does not read ov.conf. It only needs the OpenViking address, so an existing open-source or OpenViking Cloud service needs no configuration change.

1. Run openviking-gateway init. It asks for the OpenViking address and checks it (showing the server's authentication mode and version), the listen address (127.0.0.1:1935 by default), and whether to require a management key. It writes ~/.openviking/gateway.conf, or the file named by --config, readable only by you:

   {
     "openviking_url": "https://ov.example.com",
     "host": "127.0.0.1",
     "port": 1935
   }

2. Run openviking-gateway. It runs the startup checks and then listens on the address you chose.

3. Open the gateway's /studio/ and sign in with the API key of an OpenViking user, account admin or root. You should see the gateway pages and a connection page that shows which OpenViking address the gateway uses.

4. Add upstreams by hand. A standalone gateway cannot read the remote server's VLM settings, so it cannot import model settings.

To change the settings later, run openviking-gateway init again: it offers the current values as defaults and keeps existing secrets unless you change them.

Where the settings come from

The only command-line flag is --config. When --config or OPENVIKING_GATEWAY_CONFIG_FILE is set, it must point to an existing file; otherwise the gateway reads the first of ~/.openviking/gateway.conf and /etc/openviking/gateway.conf that exists. Environment variables override any field in it, so a container needs no file at all: set OPENVIKING_GATEWAY_OPENVIKING_URL, plus for example OPENVIKING_GATEWAY_HOST=0.0.0.0.

Without an OpenViking address from either source, the gateway exits and asks you to run openviking-gateway init or set OPENVIKING_GATEWAY_OPENVIKING_URL. Every field and the override rule are in the Configuration reference.

Startup checks

Before it starts, a standalone gateway contacts OpenViking once:

• If OpenViking uses trusted authentication, the gateway refuses to start.
• When the gateway binds to a non-loopback address, it starts only after confirming that OpenViking uses api_key authentication. If OpenViking is unreachable or runs in local dev mode, the gateway exits. Start OpenViking first, or bind to 127.0.0.1.
• When OpenViking runs on another host, connect over TLS or a private network.

Connecting to the public OpenViking service

A standalone gateway that connects to the public OpenViking service, https://api.vikingdb.cn-beijing.volces.com/openviking, without a management key is open to that service's users. The startup log shows the public_openviking_without_management_key warning, and Studio shows This gateway is open to every OpenViking Cloud user: anyone with an API key for that service can sign in to this gateway and change the upstreams in their account.

If the gateway is only for you or your team, set OPENVIKING_GATEWAY_MANAGEMENT_KEY and restart to restrict changes. This does not limit who can sign in or whether they can issue gateway keys for themselves.

Routes

Every gateway URL is under /gateway, in both forms. An embedded server hands the whole /gateway prefix to the gateway and keeps every other path for itself:

Path prefix	Purpose
/gateway/v1/	Model APIs and the model list
/gateway/api/v3/	Ark-compatible clients
/gateway/api/compatible/v1/	Ark Anthropic-compatible clients
/gateway/uploads	Tool uploads
/gateway/downloads	Tool downloads
/gateway/admin/	Management API (authenticated)

Clients therefore use these base URLs, with http://127.0.0.1:1933 replaced by your server's address. Per-client settings are in Connect clients.

Client	Base URL
Claude Code and Anthropic SDKs	http://127.0.0.1:1933/gateway
OpenAI-compatible clients and SDKs, including Codex, OpenCode, pi and Open WebUI	http://127.0.0.1:1933/gateway/v1
Volcano Engine Ark and BytePlus ModelArk SDKs	http://127.0.0.1:1933/gateway/api/v3

/health stays the server's own health check; an embedded gateway has no separate /health. A standalone gateway serves the same /gateway paths on its own port, plus two at the root:

• / redirects to /studio/, where Studio has only the gateway and connection pages.
• /health returns service: "openviking-gateway", auth_mode and openviking_url, and also the caller's identity when the request carries a valid OpenViking credential.

Public address

The public address, public_url, is the address clients use to reach the server (or the standalone gateway), written without /gateway; the gateway appends /gateway itself. It is empty by default, and then an embedded gateway uses the server's public address (OPENVIKING_PUBLIC_BASE_URL or server.public_base_url). Set it for every shared deployment, and always when a reverse proxy is in front:

• Embedded: set gateway.public_url in ov.conf, then restart the server.
• Standalone: set public_url in gateway.conf, or OPENVIKING_GATEWAY_PUBLIC_URL, then restart the gateway.

Two things are built from it:

• Studio's setup guides: Anthropic clients use <public_url>/gateway, and OpenAI-style clients <public_url>/gateway/v1.
• Upload and download links for OpenViking tools, unless mcp_file_links is direct; see Import files and skills.

With no public address at all, the guides use the scheme and host the request reached the server with. Behind a reverse proxy this can be an internal or http:// address, and the Connect tab warns Clients may not be able to reach this address; for a loopback address such as 127.0.0.1, it warns Only the gateway's own machine can use this address.

Reverse proxy and HTTPS

Forward the whole site to the server (embedded) or to the gateway (standalone); no path-based routing is needed. With Caddy:

ov.example.com {
    reverse_proxy 127.0.0.1:1933 {
        flush_interval -1
    }
}

Whatever proxy you use, it needs these settings:

Setting	Value	Why
Response buffering	Off	Streamed output arrives in real time
Request body size	At least 32 MiB	The gateway's own default limit for requests and uploads; long conversations send their full history (Side effects)
Read timeout	At least 600 seconds	The gateway waits up to 600 seconds for a provider by default
Logging of /gateway/uploads and /gateway/downloads	Leave out the query strings	They carry one-time tokens

Set up authentication and the public address before you expose the service; see Public access.

Keys and credentials

The gateway involves four keys, each with one job:

Key	Purpose	Where it is used
OpenViking API key	Signs in to Studio; decides which account and user memory is read and written as	X-API-Key or Authorization: Bearer on management requests
Gateway key (ovgw_…)	Connects a client; each one binds a user, a context profile and a set of upstreams (Gateway keys)	The client's API key field
Gateway management key (optional)	Restricts who can change upstreams and context profiles	gateway.management_key; the X-OpenViking-Gateway-Management-Key request header
Upstream API key	Calls the model provider (Credentials)	The upstream editor

The gateway has no encryption key of its own: it encrypts its local storage with OpenViking's encryption settings; see Encryption.

Gateway management key

The gateway management key is an optional deployment secret that restricts who can change upstreams and context profiles. It is not set by default, so every signed-in user in an account can add and change that account's upstreams and context profiles. Once it is set, only requests that carry it can change them, OpenViking admins and root included. It does not limit who can sign in, or whether users can issue gateway keys for themselves.

What read-only users can still see and do in Studio is in Who can change what; the full rules, including the management API, are in the access matrix.

Treat it as a deployment secret. The management key also works on its own, without an OpenViking API key: with account_id it can read, create, change and delete upstreams and context profiles in any account, including pointing an upstream at a different provider address. It cannot read memory or logs, or issue gateway keys. Share it only with the people who maintain upstreams.

To set one:

• openviking-server init (embedded): for a remote deployment, answer no to Allow users to configure their own gateway upstreams?. Init generates a value starting with ovgm_, prints it and saves it to gateway.management_key in ov.conf.
• openviking-gateway init (standalone): answer yes to Require a management key to change upstreams and profiles?. Init generates an ovgm_ value, prints it once and saves it to management_key in gateway.conf.
• Studio (embedded, root): the confirmation dialog of Enable gateway has a checkbox, Only people with the gateway management key can change upstreams and context profiles, which is off by default. If you check it, Studio generates an ovgm_ value, saves it to gateway.management_key in ov.conf along with gateway.enabled: true, and shows it once.
• By hand: use at least 32 characters, for example from openssl rand -base64 32. Put it in management_key, or set the OPENVIKING_GATEWAY_MANAGEMENT_KEY environment variable, which overrides the file in both forms; see Configuration reference.
• Compose and Helm: Compose passes OPENVIKING_GATEWAY_MANAGEMENT_KEY into the container; Helm reads it from the management-key entry of the Secret named in gateway.existingSecret. See Docker Compose and Helm.

There is no command-line flag for the management key, because flags show up in process lists and shell history. Setting, changing or removing it takes a restart. It does not revoke issued gateway keys or change existing upstreams and context profiles.

Lost the management key

If nobody has the gateway management key, look where the gateway reads it from, in this order:

1. The OPENVIKING_GATEWAY_MANAGEMENT_KEY environment variable, which wins over the files. Compose usually sets it in the .env file next to docker-compose.yml; Helm reads it from the management-key entry of the Secret named in gateway.existingSecret.
2. Otherwise, gateway.management_key in ov.conf (embedded) or management_key in gateway.conf (standalone). A value written as $VAR lives in that environment variable.

On an embedded gateway, root can also open ov.conf in Studio under Settings → Server configuration → File editor. Keys generated by openviking-server init and by Studio's Enable gateway are stored there in plain text.

If you can't recover it, replace it:

1. Generate a new value of at least 32 characters, for example with openssl rand -base64 32.
2. Put it in the same place. An empty environment variable does not clear the value in the file; unset the variable instead.
3. Restart. With Compose, a change in .env takes effect only after docker compose up -d, not docker compose restart.
4. In Studio, choose Enter gateway management key and paste the new value. Issued gateway keys, upstreams and context profiles are unaffected.

Encryption

The gateway encrypts stored credentials and conversation state with OpenViking's own encryption (see the Encryption guide). When encryption is off or not configured, the gateway stores everything in plain text, protected only by file permissions.

• Embedded: the gateway follows the server's encryption section in ov.conf. There is nothing to set for the gateway itself.

• Standalone: add an encryption block to gateway.conf. It has exactly the same fields as the encryption section of ov.conf, for example:

  {
    "openviking_url": "https://ov.example.com",
    "encryption": {
      "enabled": true,
      "provider": "local",
      "local": { "key_file": "~/.openviking/master.key" }
    }
  }

Changing the setting later:

• Turning encryption on is safe: values written before stay readable, and new writes are encrypted.
• Turning it off, or switching to a different encryption root key, makes the encrypted values unreadable, so keep the settings the data was written with.
• Losing the encryption root key makes the gateway's databases unreadable. Back it up as the Encryption guide describes.

Data written by the v0.5 gateway, which used its own key, is converted on the first start; see Migration.

Scaling

One storage directory serves one deployment on one host, and an embedded and a standalone gateway must not share a directory. An embedded gateway follows the server's worker setting; a standalone gateway takes workers, from 1 to 64. For load balancing, failover or rate limiting across providers, add a service such as LiteLLM as an upstream.

Monitoring and routine checks

The gateway exports no metrics such as Prometheus and writes no HTTP access log. Check its state on Studio's Overview and Requests tabs, or through the management API's /gateway/admin/overview and /gateway/admin/logs.

Routine checks

• Liveness: /health, which is the server's health check in an embedded deployment and the gateway's own in a standalone one.
• Gateway health: the First-call cache hit rate on the Overview tab (what it means). If it drops noticeably, see The first-call cache hit rate dropped.
• A single request: expand its row on the Requests tab; see Requests.
• Public address: public_url still matches the address clients use; see Public address.
• Backups: the storage directory and, with encryption on, the encryption root key; see Backups and recovery.

Upgrades

• Read the release notes before you upgrade. If a new gateway version cannot read the old storage format, it stops at startup with Unsupported gateway schema; see The gateway does not start.
• A standalone gateway needs OpenViking Server min_server_version (0.4.16) or later. With an older server, no keys can be issued and saving retries fail with openviking_version_mismatch; memory search may also fail, shown as openviking_http_<status>. When you upgrade the two separately, upgrade OpenViking first, then the gateway. An embedded gateway ships with its server and skips this check.
• To move from the sidecar or an older standalone gateway, see Migration.

Migration from earlier releases

These steps apply when you move from the sidecar or standalone gateway of earlier releases to the embedded gateway. Steps 4 and 7 are detailed in the tables after the list.

1. Back up first. Back up storage_path (both databases and encryption.key, if it is there). Stop the old gateway process or sidecar before you enable the embedded gateway.

2. Remove old fields. Delete host, port, workers, url, openviking_url, admin_token_env and encryption_key_env from the gateway section of ov.conf. The server ignores them and logs a warning at startup, so an old ov.conf still starts, but clean them up; openviking-server init → Update gateway removes them for you.

   To keep running the gateway on its own instead, run openviking-gateway init, or move its settings to a separate gateway.conf, without the gateway wrapper and enabled. The standalone command no longer takes --openviking-url, --host, --port, --workers or --storage-path; set them in gateway.conf or as environment variables.

3. Fix the public address. Point public_url at the server's public address, without /gateway, or remove it. The old quick start set it to http://127.0.0.1:1935, which the embedded gateway no longer listens on, so setup guides and upload links would point at nothing. When public_url points at another port, openviking-server init → Update gateway offers to clear it.

4. Update client addresses and deployment config. Every gateway URL now lives under /gateway, so clients change both the port and the path, and the old paths are not served any more; see New addresses. Remove the old 1935 Service and Ingress routes, the Compose gateway service and profile, and the Helm sidecar settings gateway.workers, gateway.port and gateway.resources.

5. Let the first start convert stored data. The v0.5 gateway encrypted its data with its own key. On the first start, the new gateway (embedded or standalone) decrypts it with that key and rewrites it under the current encryption settings, or in plain text when encryption is off, so turn on OpenViking encryption before this start if you want the data to stay encrypted.

   The old key is read from the OPENVIKING_GATEWAY_ENCRYPTION_KEY environment variable, or from encryption.key in storage_path. encryption_key_env is ignored: if you used it to point at another variable, export the key as OPENVIKING_GATEWAY_ENCRYPTION_KEY for this start. If old encrypted data exists and neither source has the key, the gateway refuses to start and the error names both places. With Helm, keep the encryption-key entry in the existingSecret Secret for the upgrade release only. After a successful start the old key is never read again, so you can remove the variable, the Secret entry and encryption.key.

6. Remove the shared admin token. OPENVIKING_GATEWAY_ADMIN_TOKEN is not used as a management key. To restrict who can change upstreams and context profiles, set management_key explicitly; see Gateway management key.

7. Check upstream addresses. On the first start, the gateway rewrites stored Base URLs once, so each upstream keeps calling the same address as before the upgrade; see How stored upstream addresses change. Use Test on the Upstreams tab to confirm each one still answers.

8. Note the changes to logs and revocation. Request logs gain a user column; older records have no user and appear only in account admin and root views. Revoking a key no longer deletes the user's data; explicit deletion and retention still apply.

New addresses

Replace host with your server's address:

What	Before	After
OpenAI-compatible clients	http://host:1935/v1	http://host:1933/gateway/v1
Claude Code ANTHROPIC_BASE_URL	http://host:1935	http://host:1933/gateway
Volcano Engine Ark and BytePlus ModelArk SDKs	The old gateway address	http://host:1933/gateway/api/v3
Scripts that call the management API	/api/v1/admin/gateway/...	/gateway/admin/...

1935 is still the standalone default port, and a standalone gateway uses the same /gateway paths.

How stored upstream addresses change

Upstream	Stored Base URL	After the first start
Ark and ModelArk, Chat Completions or Responses	Only a domain	/api/v3 added
Other Chat Completions or Responses	A path that does not end in a version segment such as /v1 or /v4, including a bare domain or a path prefix	/v1 added: https://api.deepseek.com → https://api.deepseek.com/v1, https://openrouter.ai/api → https://openrouter.ai/api/v1, or a self-hosted proxy under /litellm
Ark and ModelArk, Anthropic	Only a domain	/api/compatible added
Anthropic	Ends in /v1	/v1 removed
Any	Already ends in another version segment, such as Zhipu's https://open.bigmodel.cn/api/paas/v4	Unchanged. Before the upgrade it became …/v4/v1 and failed; now it works as entered.

New and edited upstreams follow the rules in How the Base URL is joined, and an Anthropic Base URL ending in /v1 is rejected.

Next steps

• Manage OpenViking Gateway in Studio: add upstreams, create context profiles and issue the first gateway keys.
• Security and data: review what the gateway stores, who can reach it, and how to back it up and delete data.
• Troubleshoot OpenViking Gateway: match a startup error, setup card or failed request to its fix.