Skip to main content

verdictan gateway

The verdictan gateway command group includes local supervisor definitions, runtime inspection, reload or revert workflows, and OS service management. It also gives a different remote inventory view.

Preflight a runtime config​

Resolve providers, credentials, routing, and the policy chain without starting a server:

verdictan gateway check --config policy-config.yaml

Use --verbose to expand provider-readiness details. The command reports the config version and digest. It also reports providers, routing strategy, policy chain, and a last Ready or Not Ready result.

Run it with the same environment and secret-store access as the specified service. gateway check does not start a process, send a provider inference, or deploy a config. It does not prove that application traffic uses the gateway. See Config Validation for the complete preflight sequence.

Local definitions and inventory​

Create a local supervisor definition​

verdictan gateway create \
  --name production \
  --listen 127.0.0.1:41002 \
  --upstream https://api.openai.com

create writes local supervisor state. It does not register a gateway in the Verdictan control plane and does not start the process.

List local gateways​

verdictan gateway list

List remote gateways​

verdictan gateway list --remote

The local list reads supervisor state without an API token. --remote calls GET /v1/gateways. API authentication is necessary for this call.

Inspection and runtime state​

Examine a named gateway​

verdictan gateway inspect --name verdictan-proxy

Read a running gateway config endpoint​

verdictan gateway config --gateway-url http://127.0.0.1:41002

Use --expect-version or --expect-sha256 to verify the runtime version or digest. The command fails when it finds an unexpected value. If the runtime protects its admin endpoints, set VERDICTAN_API_TOKEN in the environment before running the command.

Diff local service state​

verdictan gateway diff --name verdictan-proxy

Reload a running gateway​

verdictan gateway reload \
  --name verdictan-proxy \
  --gateway-url http://127.0.0.1:41002

Reload reads the definition's configured policy paths unless you supply --config-path. It records the active config as a rollback target. Then it posts the new YAML and verifies the active version and digest. It tries an automatic rollback if the activation check fails.

Revert a running gateway​

verdictan gateway revert \
  --name verdictan-proxy \
  --gateway-url http://127.0.0.1:41002

Revert works only if the named local definition has a saved rollback target from an earlier reload.

Reconcile gateway state​

verdictan gateway reconcile --name verdictan-proxy

Use --all to reconcile all known gateways. Use --apply-rollback to apply a pending rollback. Use --cancel to cancel the pending action.

Service installation​

Install a local service​

verdictan gateway install \
  --name verdictan-proxy \
  --listen 127.0.0.1:41002 \
  --upstream https://api.openai.com

If you install from policy-config.yaml, use the same settings as verdictan gateway run. Bind the service to an agent. Set Verdictan API authentication.

Use --agent-id <id> for a direct binding or --agent-name <name> to resolve by name. Put the runtime token in VERDICTAN_API_TOKEN. Do not put it directly in the command line. Installation targets a macOS launchd user service or Linux systemd user service.

The examples bind only to loopback. If the host has deliberate inbound traffic, firewall, TLS, and application-token controls, you can select an all-interface listener.

Start, stop, status, and uninstall​

verdictan gateway start --name verdictan-proxy
verdictan gateway status --name verdictan-proxy
verdictan gateway stop --name verdictan-proxy
verdictan gateway uninstall --name verdictan-proxy

verdictan gateway status and verdictan gateway uninstall use verdictan-proxy when you do not include --name. Include the name to make scripts clear.

Runtime binary upgrades​

Upgrade operations work on a configured local supervisor definition. Record a plan. Apply it. Examine the result. Alternatively, return to the recorded rollback binary:

TARGET_BINARY=/opt/verdictan/verdictan-next

verdictan gateway upgrade plan \
  --name verdictan-proxy \
  --target-version next \
  --binary-path "$TARGET_BINARY"

verdictan gateway upgrade apply --name verdictan-proxy
verdictan gateway upgrade status --name verdictan-proxy --json
verdictan gateway upgrade rollback --name verdictan-proxy

apply can also accept the plan fields directly. Optional health checks run after the service update. A failed check marks the upgrade as failed. These commands do not prompt before plan, apply, or rollback. Before you run these commands, review the target and rollback paths.

Next steps​