Skip to main content

verdictan gateway supervise

Use verdictan gateway supervise when a desktop application must own the lifetime of authenticated local gateways. The parent application supplies JSON Lines control messages and reads lifecycle events. The gateways bind to loopback addresses with ports selected by the operating system.

For a gateway in a terminal, use verdictan gateway run. For a host service, use verdictan gateway install. The desktop supervision interface does not use saved service definitions.

Usage​

verdictan gateway supervise
verdictan gateway supervise --multi
OptionEffect
--multiHost multiple gateway attachments and their runtimes in one supervisor process. The default is single-gateway mode.

The command has no --listen, --name, --state-dir, --json, or credential flag. Its output is already JSON Lines. Gateway identity, API origin, and expiry come from the protected runtime credential.

Prepare the parent application​

  1. Complete desktop authorization for the selected account profile.
  2. Read the account supervisor's capabilities before runtime provisioning.
  3. Obtain runtime credentials through the account supervisor's protected export channel.
  4. Start the child process with a private pipe or socket inherited as descriptor 3.
  5. Keep standard input open while the parent owns the gateways.
  6. Read lifecycle events from standard output.

Send credentials only through descriptor 3. A regular file does not meet the protected-channel requirement. Do not put runtime credentials in control messages, command arguments, URLs, or logs. An ordinary VERDICTAN_API_TOKEN does not replace this channel.

The credential frame contains these fields:

FieldMeaning
schema_versionProtocol value 1.
generationPositive integer credential generation.
runtime_id, runtime_registration_id, session_id, agent_idUUID identifiers issued for the runtime.
gateway_idGateway identifier.
api_urlAPI origin for this runtime.
expires_atCredential expiry as an RFC 3339 timestamp.
runtime_credential, inference_credentialSeparate credentials for runtime management and model requests.
provider_access_modeOptional mode: byok, codex_subscription, or claude_subscription.
correlation_idRequired for pairing a multi-gateway attach or renewal with its control request.

Use the issued frame. Do not construct or replace its credentials locally. Protected frames have an 8,192-byte limit.

Single-gateway mode​

The parent writes one newline-terminated credential frame to descriptor 3 during startup. The CLI waits up to five seconds for that frame. It starts one gateway and emits gateway.starting, followed by gateway.listening when the listener is available. Use the returned effective_address for that process.

Each event includes schema_version, correlation_id, generation_id, sequence, runtime_generation, event, and data. The process creates generation_id. It increments sequence for each emitted event. Copy the live generation into subsequent control requests.

OperationRequired fields beyond the common envelopeResult
gateway.statusNoneEmit the gateway state, address, expiry, and readiness requirement.
gateway.shutdownNoneStop the gateway and emit stopping and stopped events.

The common request envelope contains schema_version: 1, correlation_id, generation_id, and operation. Correlation IDs contain 1 through 128 ASCII letters, digits, underscores, or hyphens.

This control-frame template contains no credentials. Replace GENERATION_ID with the UUID from the live process:

{"schema_version":1,"correlation_id":"status-1","generation_id":"GENERATION_ID","operation":"gateway.status"}

A shutdown request uses the same envelope with operation: "gateway.shutdown" and a new correlation ID. Closing standard input also stops the gateway. Credential expiry, revocation, and parent cancellation stop it independently of further input. Single-gateway mode has no credential-renewal control operation.

Multi-gateway mode​

Start the child with --multi and keep the protected credential pipe open. Wait for supervisor.ready before sending control requests. The event reports generation_id, capabilities, and capacity limits. Require gateway.supervise.multi before using this interface.

Use a new correlation ID for each request. Include the live generation ID in each request. Multi-gateway events also include gateway_id, runtime_id, and runtime_generation, which can be null for supervisor events.

OperationAdditional control fieldsResult
gateway.attachgateway_id, agent_idAttach a gateway for an agent and return its shared loopback address.
gateway.detachgateway_idStop its runtimes and remove the attachment.
gateway.statusgateway_idRead one gateway and its runtime summaries.
gateway.listNoneRead all attached gateways.
runtime.attachgateway_id, runtime_idAttach a runtime using a paired protected credential frame.
runtime.detachgateway_id, runtime_idStop and remove that runtime.
credential.renewgateway_id, runtime_idRenew an attached runtime using a paired protected credential frame.
supervisor.shutdownNoneStop all runtimes and gateways, then stop the supervisor.

For runtime.attach and credential.renew, write the credential frame to descriptor 3 with the request's correlation_id. The supervisor waits up to five seconds for the paired frame. Its gateway, agent, and runtime identifiers must match the requested attachment. A renewal must retain runtime registration and session identifiers and increase the credential generation. Renewal preserves the running gateway and requests already in progress.

A typical parent-client sequence is:

  1. Read supervisor.ready and retain its generation ID.
  2. Send gateway.attach with the selected gateway and agent identifiers.
  3. Retain the address from gateway.attached.
  4. Send runtime.attach and its paired protected frame.
  5. Wait for runtime.attached before examining readiness for that runtime.
  6. Send model requests with that runtime's inference credential to the gateway's shared address.
  7. Renew the runtime before credential expiry.
  8. Send runtime.detach when its conversation ends.
  9. Send supervisor.shutdown when the parent releases the supervisor.

The current limits are 16 gateways, 16 runtimes per gateway, and 64 runtimes per process. The supervisor permits up to 16 concurrent control operations. Use the limits reported by the running process when managing capacity. A broken protected channel prevents new attach and renewal operations. Existing runtimes remain subject to expiry and revocation.

Readiness and evidence​

A listening gateway does not establish permission to execute an agent. Supervisor status reports ready: false with reason_code: "desktop.readiness_required". The client must examine authenticated desktop readiness before dispatch. Each actual model request still requires policy evaluation and usage authorization.

For a runtime, the desktop readiness route is:

GET /verdictan/desktop/readiness?runtime_id=RUNTIME_ID&session_id=SESSION_ID&agent_kind=AGENT_KIND&agent_version=AGENT_VERSION

Replace the uppercase values with the bound runtime, session, agent kind, and actual agent version. Use the returned loopback address and the runtime's inference credential in the Authorization bearer header. The agent kinds are codex and claude_code. A successful readiness response still requires authorization for each request. Readiness does not prove audit delivery or usage settlement.

Limits and failure behavior​

ConditionResult and action
Missing or unsuitable protected channelStartup or runtime attachment fails. Supply an inherited private pipe or socket.
Missing, malformed, or expired credentialThe runtime cannot start. Obtain a current frame from the account supervisor.
Stale process generation or invalid operationThe supervisor emits desktop.invalid_gateway_command. Use the live generation and supported operation.
Duplicate multi-gateway correlation IDThe supervisor emits desktop.duplicate_request. Use a new ID.
Renewal does not increase credential generationThe supervisor emits desktop.runtime_generation_conflict. Obtain a newer credential.
Runtime credential expires or is revokedThe affected runtime stops. Read the expiry or revocation event before obtaining another runtime.
Capacity is exhaustedRelease unused attachments before requesting more capacity.
Parent closes standard inputThe supervisor stops its owned runtimes and gateways.

Detaching a runtime or gateway stops its active work. These protocol operations do not prompt for terminal confirmation. Do not repeat a model request to recover missing lifecycle or audit information.

Complete command reference​

Select a command for its complete input table. Default input means the value used when that option is omitted. A value marked Not set can still come from configuration or the environment, as described above. Set uppercase variables in example templates to your own resource IDs and paths before use. See CLI scripting for quoting, output streams, confirmation, and exit codes.

Next steps​