Manage OpenViking Gateway in Studio
This page is for anyone who uses the gateway pages in Studio: what each tab is for, who can change what, and when saved changes take effect. Open Studio with your OpenViking API key (a server in local dev mode needs none) and choose OpenViking Gateway in the sidebar; a standalone gateway serves its own Studio at /studio/. Upstreams and context profiles are shared by everyone in an OpenViking account, while gateway keys and request logs belong to each user.
Studio tabs
The gateway pages have six tabs. Each row links the page that explains the tab in detail.
| Tab | What it is for | Whose data | Explained in |
|---|---|---|---|
| Overview | Health at a glance: request count, cache hit rates, recalled memory, OpenViking status and degraded requests. Before the first request, it shows the Get started checklist. | Your requests; account admins and root see the whole account | Overview, Get started checklist |
| Upstreams | Add, edit, test and import the model endpoints the gateway forwards requests to. | Shared by the account | Upstreams |
| Profiles | Create and edit context profiles: recall, saving, long conversations and OpenViking tools. | Shared by the account | Context profiles |
| Keys | Issue and revoke gateway keys; account admins and root can also delete a user's gateway data. | Your keys; account admins and root manage the whole account | Gateway keys |
| Requests | The request log: each model request with its memory, tokens, issues and saving status. | Your requests; account admins and root see the whole account | Requests |
| Connect | The gateway address and copy-ready settings for each client. | Same for everyone | Connect clients |
Who can change what
Whether you can edit upstreams and context profiles depends on one deployment setting: the gateway management key. It is not set by default, and whoever deploys the gateway decides whether to set it.
| Action in Studio | No management key set | Management key set |
|---|---|---|
| View upstreams and context profiles, and pick them when issuing a key | Every signed-in user in the account | Every signed-in user; read-only views leave out upstream API keys and headers |
| Add, change or delete upstreams and context profiles | Every signed-in user in the account | Only after you unlock editing, account admins and root included |
| Test an upstream (connection test or model test) | Every signed-in user in the account | Only after unlocking; while Studio is read-only, the Test button is hidden |
| Import OpenViking model settings (embedded deployments only) | Root only, including local dev mode | Only after unlocking |
| Issue gateway keys | Users for themselves; account admins for users in their account; root first switches account in the sidebar | Same; the management key adds no rights |
Testing needs write access because a test uses the stored credentials, and a model test is billed by the provider. Key issuing is covered in Gateway keys, and the full rules, including the management API, are in the access matrix.
If no usable upstream or context profile exists yet and you cannot change them, the Get started checklist says it is waiting for your gateway admin. Ask whoever deployed the gateway.
Unlock editing
When a gateway management key is set, the Upstreams and Profiles tabs are read-only until you unlock them in your browser tab. An account admin's or root's API key does not unlock them, and neither does a gateway key (ovgw_…).
- On the Upstreams or Profiles tab, choose Enter gateway management key in the read-only notice.
- Paste the management key and choose Unlock. Keys generated by
openviking-server init,openviking-gateway initor Studio's Enable gateway start withovgm_; Where can I find it? in the dialog lists where it is stored. - You should see Unlocked. You can now edit upstreams and profiles., and the page header shows Editing upstreams and profiles with a Lock button.
Editing stays unlocked only in that browser tab, until you choose Lock or close the tab. If the management key is changed on the server, Studio locks again on its own and shows The gateway management key is no longer valid. Upstreams and profiles are read-only again. If nobody has the key, see Lost the management key.
Get started checklist and Quick mode
The Get started checklist sits on the Overview tab until the first request arrives. It lists four steps in order: Add an upstream, Create a context profile, Issue a gateway key and Connect a client. Once a client sends its first request, the checklist goes away.
Until the first gateway key exists, the checklist also shows a Quick mode card. Get a key does the first three steps in one click:
| Step | What Quick mode does |
|---|---|
| Upstream | Uses the usable upstreams you already have. If there is none, it imports OpenViking's own model settings (the VLM models in ov.conf) as upstreams. |
| Context profile | Uses an existing context profile. If there is none, it creates one named "Default" with the recommended settings. |
| Key | Issues a key named "Quick mode" for the current user, bound to every usable upstream. Outside local dev mode, root picks the key's user in the issue dialog instead. |
An upstream counts as usable when all of these hold:
- it is enabled;
- the gateway stores its API key (it is not set to Each client sends its own key) and a key is saved;
- it lists at least one model or alias (an empty Models list does not count, so Quick mode still imports model settings even if you already have such an upstream);
- it is not a Coding Plan upstream that is still blocked.
Exceptions:
- If the imported settings still give no model the gateway can relay directly, the card says so, and you add an upstream yourself in step 1 (Add an upstream).
- When a management key is configured and Quick mode needs to create a context profile or import models, the card first asks you to unlock with the management key.
- Only some users can import model settings: root (or anyone in local dev mode) when no management key is set, and whoever unlocks with the management key when one is set. A standalone gateway cannot import them at all. If you can't import, the card appears only once a usable upstream exists.
When changes take effect
Saved changes to an upstream or a context profile apply to every gateway key that uses it, so you never need to reissue keys for them. What differs is whether a conversation that is already under way sees the change:
| What you change | When it applies |
|---|---|
| Any upstream setting except priority, such as the API key, models or Enabled | At once, in ongoing conversations too. For what turning an upstream off does to its conversations, see Routing. |
| Upstream priority | Only in conversations that start afterwards. An ongoing conversation stays on its upstream as long as that upstream can still serve it. |
| Any context profile setting | Only in conversations that start afterwards. |
| A gateway key | Keys cannot be edited. To change a key's context profile, upstreams, allowed models or user, issue a new key and revoke the old one; see After issuing. |
A conversation records its context profile at its first request and keeps it, because changing what the model sees mid-conversation would break the provider's prompt cache. How soon a client picks up a profile change therefore depends on how often it starts a new conversation:
- Clients that open a new conversation for every chat pick up changes quickly.
- Claude Code, Codex and clients that send a fixed session header can continue one conversation for days. They keep the old settings until they start a new conversation, or until the conversation has been idle for 30 days (
session_ttl_days), when the gateway deletes its state.
How the gateway tells conversations apart is explained in How conversations are recognized.
Next steps
- Get started with OpenViking Gateway: go from an empty gateway to a working key and a test request.
- Gateway management key: set, change or reset the key that protects upstreams and context profiles.
- Studio shows a setup card: what to do when Studio shows a setup card instead of the gateway tabs.