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| Option | Effect |
|---|---|
--multi | Host 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
- Complete desktop authorization for the selected account profile.
- Read the account supervisor's capabilities before runtime provisioning.
- Obtain runtime credentials through the account supervisor's protected export channel.
- Start the child process with a private pipe or socket inherited as descriptor 3.
- Keep standard input open while the parent owns the gateways.
- 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:
| Field | Meaning |
|---|---|
schema_version | Protocol value 1. |
generation | Positive integer credential generation. |
runtime_id, runtime_registration_id, session_id, agent_id | UUID identifiers issued for the runtime. |
gateway_id | Gateway identifier. |
api_url | API origin for this runtime. |
expires_at | Credential expiry as an RFC 3339 timestamp. |
runtime_credential, inference_credential | Separate credentials for runtime management and model requests. |
provider_access_mode | Optional mode: byok, codex_subscription, or claude_subscription. |
correlation_id | Required 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.
| Operation | Required fields beyond the common envelope | Result |
|---|---|---|
gateway.status | None | Emit the gateway state, address, expiry, and readiness requirement. |
gateway.shutdown | None | Stop 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.
| Operation | Additional control fields | Result |
|---|---|---|
gateway.attach | gateway_id, agent_id | Attach a gateway for an agent and return its shared loopback address. |
gateway.detach | gateway_id | Stop its runtimes and remove the attachment. |
gateway.status | gateway_id | Read one gateway and its runtime summaries. |
gateway.list | None | Read all attached gateways. |
runtime.attach | gateway_id, runtime_id | Attach a runtime using a paired protected credential frame. |
runtime.detach | gateway_id, runtime_id | Stop and remove that runtime. |
credential.renew | gateway_id, runtime_id | Renew an attached runtime using a paired protected credential frame. |
supervisor.shutdown | None | Stop 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:
- Read
supervisor.readyand retain its generation ID. - Send
gateway.attachwith the selected gateway and agent identifiers. - Retain the address from
gateway.attached. - Send
runtime.attachand its paired protected frame. - Wait for
runtime.attachedbefore examining readiness for that runtime. - Send model requests with that runtime's inference credential to the gateway's shared address.
- Renew the runtime before credential expiry.
- Send
runtime.detachwhen its conversation ends. - Send
supervisor.shutdownwhen 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_VERSIONReplace 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
| Condition | Result and action |
|---|---|
| Missing or unsuitable protected channel | Startup or runtime attachment fails. Supply an inherited private pipe or socket. |
| Missing, malformed, or expired credential | The runtime cannot start. Obtain a current frame from the account supervisor. |
| Stale process generation or invalid operation | The supervisor emits desktop.invalid_gateway_command. Use the live generation and supported operation. |
| Duplicate multi-gateway correlation ID | The supervisor emits desktop.duplicate_request. Use a new ID. |
| Renewal does not increase credential generation | The supervisor emits desktop.runtime_generation_conflict. Obtain a newer credential. |
| Runtime credential expires or is revoked | The affected runtime stops. Read the expiry or revocation event before obtaining another runtime. |
| Capacity is exhausted | Release unused attachments before requesting more capacity. |
| Parent closes standard input | The 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.
verdictan gateway supervise [OPTIONS]| Input | Required | Default input | Meaning and accepted values |
|---|---|---|---|
--multi | No | false | Host one gateway for each attached agent in this process This is a switch without a value. |
--help (-h) prints help. The global --lang and --region options follow the shared input rules.
The parent must supply a protected credential pipe. Standard output carries JSON Lines lifecycle events. A listener event does not authorize model execution.
Result: A JSON Lines lifecycle event stream. With --multi, supervisor, gateway, and runtime events identify their respective attachments.
Next steps
- verdictan auth: authorize the parent account supervisor.
- verdictan acp: connect managed coding-agent conversations.
- verdictan gateway: manage host services and local definitions.