Skip to main content
An extension is an optional Gateway feature. Each extension has one switch, and the Gateway stores it. The switch decides for every client whether the extension’s CLI commands, MCP tools, API operations, and web pages are available. A disabled extension is invisible in every client, and the Gateway refuses its operations.

​
Commands

Each command accepts --json. Enable and disable need Gateway access.

​
Extensions

​
What a disabled extension does

tasks:status is a core view. It stays available while tasks is disabled. Disabling an extension keeps its data, such as tasks or the proxycli collector. A nested empty object in a tool argument stays an object through a direct tools/call and through execute_tools. MCP describes that shape.

​
Extension state in the CLI

The CLI asks the Gateway for the switches at most once per process: when it lists commands or shows help, when it runs extension:list, and when it runs an extension command. The request has a 2-second deadline, which includes its one retry after a connection failure. The CLI stores no copy. When the CLI cannot read the switches, the state is unknown, not disabled. This happens when no Gateway profile is active, the Gateway CA is not trusted, or the Gateway does not answer in time.
  • extension:list shows UNKNOWN and the cause, such as gateway.profile_missing, gateway.ca_untrusted, or gateway.unreachable.
  • list and help hide the extension commands.
  • An extension command fails with extension.state_unknown and sends no request.
The gateway:* commands need no extension state, so you can add, select, trust, or remove a profile and try again.

​
orbit extension:list

List every extension with its Gateway state.
Human output is a table with the columns EXTENSION, STATE, and DETAIL. JSON returns an extensions array. Each entry has extension and enabled, which is null when the state is unknown. An unknown entry also has state, with the error code, message, and request_id.

​
orbit extension:enable

Enable one extension for every client.
JSON returns name and enabled. Enabling an enabled extension succeeds and changes nothing. Enabling only flips the switch. An extension that needs fleet resources has its own setup command, such as proxycli:setup.

​
orbit extension:disable

Disable one extension for every client.
JSON returns name and enabled. Disabling a disabled extension succeeds and changes nothing. Disabling proxycli does not stop its collector. Run proxycli:teardown for that.

​
Errors

​
Why it works this way

Each extension has one switch, and the Gateway owns it. A switch on each operator’s machine could not hide Gateway routes, MCP tools, or web pages, so two operators could see different products. A cached copy in the CLI would become a second source of truth, so the CLI asks the Gateway in each process. The switch only shows or hides. Setting up proxycli needs a Node, a cache connection, an upstream URL, and a key, so that stays in the extension’s own setup command. Every extension then keeps the same small switch contract, and one extension has one switch name. API routes stay registered while an extension is off and refuse with extension.disabled. Removing routes at runtime would make the OpenAPI document, the SDK, and the generated MCP tools change with runtime state. MCP filters tools before listing, search, and execution, so no path can find or run a disabled tool. An unknown state is not a disabled state. Treating an unreachable Gateway as “disabled” would hide commands for a reason that has nothing to do with the switch, and the operator would look in the wrong place.
  • tasks describes task operations.
  • proxycli describes collector setup, teardown, and quota commands.
  • Using the CLI describes Gateway selection.