Operator Toolkit

Operator Toolkit (nexus)

nexus is a single binary that operates and observes the gateway from your terminal. It exposes the same read and triage capabilities as the web Control Plane, reached through the same admin API and /v1/* endpoints — so everything you can do in nexus is governed by exactly the same access control (IAM) as the web console. There are three faces over one shared core: an interactive TUI, a scriptable CLI, and an MCP server for agents.

Environments and login

nexus keeps named environments (for example local, dev, prod) in a config file under your home directory. Each environment records its base URLs and the model and Virtual Key you last used; secrets never go in that file — your access token, admin key, and Virtual Key secret live in your operating system's keychain. A built-in local target works out of the box, and a one-time nexus setup points the tool at your own deployment.

You authenticate one of two ways:

• As a person — nexus login opens your browser for the standard OAuth2 + PKCE sign-in and caches the resulting token.
• As a machine — nexus login --admin-key reads an admin API key from standard input and stores it for an unattended profile.

The active environment is always visible, and a production environment is shown with a persistent red banner so you cannot mistake which deployment you are acting on.

The TUI

Running nexus with no subcommand on a terminal opens the console. On first use an entry wizard walks you through choosing an environment, signing in, picking a model, and choosing a Virtual Key. The dashboard stacks an interactive view on top and an always-on chat at the bottom; tab moves the keyboard between them — the chat is focused on launch — and the focused half grows to give your current task more room. A / command palette jumps to any view, switches the chat's model (/model), or runs an agent control; number keys jump straight to a view; ↑/↓ and enter select and open a row; esc steps back one level; and q quits.

The views cover the operator's day-to-day surface — health at a glance, a live traffic radar, single-event detail with hook decisions and a latency breakdown, provider SLOs, cost and cache ROI, a chat playground, a request lab, the emergency-passthrough kill switch, firing alerts, node health, compliance KPIs, scheduled jobs, config-sync status, the model catalog, Virtual Keys, and routing rules. Beyond these purpose-built screens, a generic Resource browser reaches every admin resource the API exposes — driven by the gateway's own API description — so even resources without a dedicated screen can be listed as a table, filtered, drilled into (including the records nested inside a record, to any depth), and, behind an Allow/Deny confirm, changed. The full per-view reference is in the Operator Toolkit feature guide.

The conversation

The bottom of the screen is always a conversation with a gateway agent: ask in plain English and watch it work. It reads live gateway state to answer questions ("what's my most expensive provider today?", "what's failing right now?") and drives the console on top for you — opening a view, filtering it, or pulling up an event — so you see it navigate as it reasons. Replies stream in with a typewriter effect, and a working indicator with an elapsed-time counter shows while it thinks. You can keep typing and sending while it works: messages you send mid-turn queue and run in order as it finishes, and esc interrupts the current turn. When it proposes a change (disabling a provider, flushing the cache, revoking a key) it pauses for your authorization — on a prod environment you confirm by typing the environment name. Because it runs through your selected model and Virtual Key, your gateway's own compliance policy applies to what it sends, so a reply can be blocked just like any other call. Switch the model it uses at any time with /model.

Mutations are confirmed

The console can take remediation actions — engage the kill switch, enable or disable a provider, flush the cached config, revoke or regenerate a Virtual Key, toggle a routing rule. In a production environment each of these requires typing the environment name to confirm, so a destructive action is always deliberate.

The CLI

Every capability is also a command, so scripts and other tools can shell out to nexus: health, the model catalog, traffic listing and inspection, cost, SLO, a chat one-shot, a pipeline simulation, a routing dry-run ("route explain"), creating a personal Virtual Key, and toggling the kill switch. A nexus resource family reaches every admin endpoint generically — search for the operation you need, then read it, or change it behind a confirmation — so scripting an admin task never waits on a purpose-built command. Add --output json for a stable JSON shape on any command, and the commands return distinct exit codes so a script can branch on success, a transport error, a usage error, an authentication prompt, an access-control denial, or a not-found. The full command reference is in the Operator Toolkit feature guide.

MCP server (for agents)

nexus mcp serve exposes the toolkit as Model Context Protocol tools over standard input/output, so an agent or a partner platform can drive the gateway without bespoke glue. The server has no access control of its own — it runs every tool as the principal of the configured admin credential, through the same admin API and IAM, so an agent's reach is exactly what that service user's policy allows. The read tiers (observe and analyze) and a no-mutation simulate tool are always available; the write (mitigate) tier — the kill switch, a cache flush, disabling a provider, toggling a routing rule, and revoking a Virtual Key — is off unless you explicitly enable it. The entity actions take a human-friendly name and resolve it for you, so a name that doesn't match fails with the list of valid names rather than acting on the wrong entity.

Virtual Keys and your traffic

Anything that sends real traffic — the chat playground, the request lab, the simulation tools — uses a Virtual Key you hold the secret for, either one you already have or one you create in the wizard. You never spend another team's quota.

Installation

nexus is a single static binary. See Installation and Deployment for the deployment models, and the Operator Toolkit feature guide for the complete view and command reference.

See also

• Using the Control Plane — the web console with the same capabilities
• API and Client Integration — driving the gateway programmatically
• Getting Started — first run and a first request
• Operator Toolkit feature guide — the full per-view and per-command reference