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. Navigation is k9s-style: a few hot-path tabs plus a : command palette to jump to any view.

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. The full per-view reference is in the Operator Toolkit feature guide.

Ask Nexus

Press > to open Ask Nexus, a natural-language bar: type a question in plain English and your selected model turns it into an action. It can jump to the right view and pre-filter it, answer a read question by pulling the relevant data and summarizing it (for example "what's my most expensive provider today?"), or explain a specific event. Ask Nexus only reads and navigates — it never changes anything on its own. Because it answers through your selected model and Virtual Key, your gateway's own compliance policy applies to what it sends, so an answer can be blocked just like any other call.

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