verdictan gateway

Use the verdictan gateway commands to check a config before you deploy it, run a gateway as a host service, and manage the config and binary of a gateway on this host. To start a gateway in the current terminal, use verdictan gateway run.

The subcommands act on four different targets:

Target	Subcommands	What they change
A local file	check	Nothing. The command reads the file only.
Local definitions and services on this host	create, inspect, diff, install, start, status, stop, uninstall, upgrade	Files in the supervisor state directory and the service manager. They do not contact the control plane.
A running gateway	config, reload, revert, reconcile	The active config of that gateway process, through its admin endpoints.
The control plane	list --remote	Nothing. The command reads the gateway list.

Before you start

• A working foreground gateway. Follow the quickstart first, and send one request that succeeds.
• For config, reload, revert, and reconcile: the admin token of the gateway in VERDICTAN_API_TOKEN. See Admin access to a running gateway.
• For list --remote: a CLI credential, from VERDICTAN_API_TOKEN or verdictan auth login.

Local definitions and shared flags

A local definition is a named record of gateway settings: listen address, upstream, policy config paths, fail mode, and credential references. verdictan gateway create writes it. The CLI also stores the status, the operation history, the reload rollback target, and the upgrade plan of each definition. The state is in ~/.verdictan/supervisor/supervisor-state.json.

inspect, diff, reload, revert, reconcile, start, and upgrade need a definition. They stop with instance <name> does not exist when there is none. install, status, stop, and uninstall also work with a service that has no definition.

The table of each subcommand lists its own flags, including --name. These flags are shared:

Flag	Applies to	Description
--state-dir <path>	All subcommands except check and config	Supervisor state directory. The default is ~/.verdictan/supervisor.
--json	create, list, inspect, diff, status, reload, revert, reconcile, upgrade	Print the result as JSON.

None of the subcommands accepts a token as a flag. The CLI stops with command-line token flags have been removed; set VERDICTAN_API_TOKEN or use a stored profile instead.

Admin access to a running gateway

config, reload, revert, and reconcile call the admin endpoints of a running gateway: GET /verdictan/config and POST /verdictan/config/reload. The CLI sends a bearer token in this order: the token from the --api-token-env or keychain reference of the definition, then VERDICTAN_API_TOKEN.

The gateway accepts the request when the token is one of these:

• The gateway runtime token of that gateway process.
• An API token that the control plane allows for gateways:read (to read the config) or gateways:deploy (to reload it).

The gateway returns 401 without a valid token, 403 when the token does not have the permission, and 502 when it cannot check the token with the control plane.

verdictan gateway check

verdictan gateway check loads a policy config and reports if it has a provider target that the gateway can use. It does not start a gateway, contact a provider, or deploy the config.

Usage

verdictan gateway check [--config <path>] [--verbose]

Options

Flag	Description
--config <path>	Policy config file. The default is policy-config.yaml.
--verbose	Also print the provider, model, base URL, and timeout of each active target, and the policy chain entries.

Examples

verdictan gateway check --config policy-config.yaml --verbose

The report shows the config version and SHA256 digest, the active and inactive provider targets, the routing strategy, and the number of policy chain entries. The last line is Status: Ready or Status: Not Ready.

The status is Not Ready when the config has no providers section, has no active target, or has a target with required: true whose credential does not resolve. Then the command prints gateway is not ready and exits with status 2. A target without required: true counts as active even when its credential variable is not set. To check credentials, run the command in the same environment as the gateway.

verdictan gateway list

verdictan gateway list prints the local definitions. With --remote, it calls GET /v1/gateways and prints the gateways that the control plane knows.

Usage

verdictan gateway list [--remote] [--json]

Options

Flag	Description
--remote	List the gateways from the control plane. Requires a CLI credential.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Connection overrides for --remote. The default profile is default.

Examples

verdictan gateway list
verdictan gateway list --remote

The local list has one line for each definition: name, lifecycle, listen address, and gateway ID. The remote list has one line for each gateway: ID, name, and status.

verdictan gateway config

verdictan gateway config reads GET /verdictan/config from a running gateway and prints the JSON response. Use it to confirm which config version is active.

Usage

verdictan gateway config --gateway-url <url> [--expect-version <version>] [--expect-sha256 <digest>]

Options

Flag	Description
--gateway-url <url>	Mandatory base URL of the running gateway, such as http://127.0.0.1:41002.
--expect-version <version>	Stop with an error when the active config_version is different.
--expect-sha256 <digest>	Stop with an error when the active config_sha256 is different.

Examples

verdictan gateway config \
  --gateway-url http://127.0.0.1:41002 \
  --expect-version 0.1.0

The config object in the response has config_version, config_sha256, config_content, and policy_chain. When the version is different, the command stops with proxy is running config version <actual> instead of <expected>.

verdictan gateway create

verdictan gateway create writes a local definition. It does not register a gateway with the control plane, and it does not start a process.

Usage

verdictan gateway create --listen <host:port> --upstream <url> [OPTIONS]

Options

Flag	Description
--listen <host:port>	Mandatory listen address.
--upstream <url>	Mandatory upstream base URL.
--name <name>	Definition name. The default is $HOSTNAME, then the system hostname.
--gateway-id <id>	Gateway ID to record. The default is the name.
--policy-config <path>	Policy config file. Repeat the flag for overlay files.
--fail-mode <allow|block>	Fail mode. The default is block.
--max-concurrency <n>	Maximum concurrent upstream requests. The default is 16.
--upstream-api-key-env <name>	Environment variable that holds the upstream credential.
--upstream-api-key-keychain-service <name>, --upstream-api-key-keychain-account <name>	Keychain entry that holds the upstream credential. Supply both.
--upstream-api-key-header <name>, --upstream-api-key-prefix <prefix>	Header name and value prefix for the upstream credential.
--api-token-env <name>	Environment variable that holds the gateway runtime token.
--api-token-keychain-service <name>, --api-token-keychain-account <name>	Keychain entry that holds the gateway runtime token. Supply both.
--admin-local-only	Limit admin endpoints to local callers. This setting is always on.

Use an environment variable or a keychain entry for each credential, not both. The definition stores the reference, not the value.

Examples

verdictan gateway create \
  --name local-example \
  --listen 127.0.0.1:41002 \
  --upstream https://api.openai.com \
  --policy-config /absolute/path/to/policy-config.yaml \
  --api-token-env VERDICTAN_API_TOKEN

The command prints created proxy instance local-example, the gateway ID, the listen address, and the upstream. Run verdictan gateway list to see the definition.

verdictan gateway inspect

verdictan gateway inspect prints one definition, its status, and its recent operation history.

Usage

verdictan gateway inspect --name <name> [OPTIONS]

Options

Flag	Description
--name <name>	Mandatory definition name.
--history-limit <n>	Number of history entries. The default is 5.
--history-action <action>	Show only one action: reload, reconcile, revert, install, start, stop, uninstall, or upgrade.
--history-json	Print only the history as JSON. You cannot use it with --json.

Examples

verdictan gateway inspect --name local-example --history-action reload --history-limit 10

verdictan gateway install

verdictan gateway install installs a gateway as a service, and checks that the service becomes active. The service manager depends on the host:

Host	Service	Service file
Linux	systemd user service	~/.config/systemd/user/<name>.service
Linux, as root	systemd system service that runs as the verdictan account	/etc/systemd/system/<name>.service
macOS	launchd agent	~/Library/LaunchAgents/com.verdictan.gateway.<name>.plist
macOS, as root	launchd daemon	/Library/LaunchDaemons/com.verdictan.gateway.<name>.plist
Windows, elevated shell	Windows service	Registered with sc.exe

On Linux, the credentials go into a separate environment file with owner-only permissions: ~/.config/verdictan/<name>.env, or /etc/verdictan/<name>.env for a system service. On macOS, the service writes its logs to ~/.verdictan/logs/ (agent) or /var/log/verdictan/ (daemon).

Usage

verdictan gateway install [--name <name>] [OPTIONS]

Options

Flag	Description
--name <name>	Service name. The default is verdictan-proxy.
--agent-id <id>	Agent ID. The service gets it as VERDICTAN_AGENT_ID. The command also reads VERDICTAN_AGENT_ID.
--agent-name <name>	Agent name, used only without an agent ID. The service gets it as VERDICTAN_AGENT_NAME. The command also reads VERDICTAN_AGENT_NAME.
--listen <host:port>	Listen address. The default is 0.0.0.0:41002.
--fail-mode <allow|block>	Fail mode. The default is block.
--max-concurrency <n>	Maximum concurrent upstream requests.
--policy-config <path>	Policy config file for the service command. See the warning below.
--upstream <url>	Accepted, but the service command does not use it.
--upstream-api-key-header <name>, --upstream-api-key-prefix <prefix>	Header name and prefix for VERDICTAN_UPSTREAM_API_KEY.

The command works in one of two ways:

• A definition has the same name. The service runs verdictan gateway start --name <name> --state-dir <dir>, so it uses the settings of the definition. The command ignores the other flags, except --agent-id and --agent-name. It copies the credentials from the references in the definition.
• No definition has that name. The service runs verdictan gateway run with --listen, --fail-mode, and, if you set them, --policy-config and --max-concurrency.

In both cases, the service environment gets VERDICTAN_API_URL (default https://api.verdictan.com), and VERDICTAN_API_TOKEN and VERDICTAN_OTLP_ENDPOINT from your shell when they are set. Without a definition, it also gets VERDICTAN_UPSTREAM_API_KEY. The command does not copy provider key variables, such as VERDICTAN_OPENAI_API_KEY, or VERDICTAN_RUNTIME_REGISTRATION_ID. The service registers itself with the control plane at startup. A later change in your shell does not change the service.

warning

Do not use --policy-config without a definition. The service then runs verdictan gateway run --policy-config without --agent. The command stops with --policy-config requires --agent. Instead, deploy the config to the agent in Configurations. Then install the service with --agent-id.

Examples

export VERDICTAN_API_TOKEN="replace-with-gateway-runtime-token"

verdictan gateway install \
  --name verdictan-proxy \
  --listen 127.0.0.1:41002 \
  --agent-id <agent-id>

verdictan gateway status --name verdictan-proxy
curl -s http://127.0.0.1:41002/readyz

The install prints installed <service manager> service verdictan-proxy and the service file path. If the service does not become active, the command stops with service <name> did not reach the active state. On Linux, the error includes the last log lines.

Give the service its provider credentials explicitly, or use a Console-managed provider key.

verdictan gateway start

verdictan gateway start starts the gateway of a definition. If a service with that name is installed, the command starts the service and returns. If not, it runs the definition in the current terminal until you press Ctrl+C.

Usage

verdictan gateway start --name <name>

Options

--name <name> is mandatory. It is the definition name.

Examples

verdictan gateway start --name local-example

With a service, the command prints started <service manager> service local-example.

verdictan gateway status

verdictan gateway status shows the state of a definition or a service.

Usage

verdictan gateway status [--name <name>] [OPTIONS]

Options

Flag	Description
--name <name>	Definition or service name. The default is verdictan-proxy.
--history-limit <n>	Number of history entries. The default is 5.
--history-action <action>	Show only one action. The values are the same as for inspect.
--history-json	Print only the history as JSON. You cannot use it with --json.

Examples

verdictan gateway status --name verdictan-proxy

When a definition has the name, the command prints the record from the state directory: lifecycle, observed config, last error, and history. It does not ask the service manager. When only a service has the name, it prints the service label, state, process ID, and service file. To see if the process serves traffic, call /readyz on the gateway.

verdictan gateway stop

verdictan gateway stop stops an installed service. It does not remove the service.

Usage

verdictan gateway stop --name <name>

Options

--name <name> is mandatory. It is the service name.

Examples

verdictan gateway stop --name verdictan-proxy

The command prints stopped verdictan-proxy. It stops with service <name> is not installed when there is no service with that name.

verdictan gateway uninstall

verdictan gateway uninstall stops the service and removes its service file. On Linux, it also removes the environment file. It keeps the local definition.

Usage

verdictan gateway uninstall [--name <name>]

Options

--name <name> is the service name. The default is verdictan-proxy.

Examples

verdictan gateway uninstall --name verdictan-proxy

verdictan gateway reload

verdictan gateway reload sends a policy config to a running gateway, and checks that the gateway activated it.

Usage

verdictan gateway reload --name <name> --gateway-url <url> [--config-path <path>]

Options

Flag	Description
--name <name>	Mandatory definition name.
--gateway-url <url>	Mandatory base URL of the running gateway.
--config-path <path>	Policy config file to send. The default is the policy config paths of the definition.

Examples

verdictan gateway reload \
  --name local-example \
  --gateway-url http://127.0.0.1:41002 \
  --config-path policy-config.yaml

The command does these steps:

1. It reads the active config from the gateway, and saves it as the rollback target of the definition.
2. It posts the new YAML to /verdictan/config/reload.
3. It reads the config again, and compares the version and digest with the file. It also checks that /healthz returns ok.
4. If a check fails, it posts the saved config back to the gateway, and stops with proxy activation failed verification and rollback was applied.

On success, it prints reloaded local-example to version <version>.

A reload changes only the running process. It does not save a version in the control plane. A connected gateway with a runtime registration pulls its assigned config every 30 seconds. This config replaces the reloaded config. The assigned config is the configuration that is deployed to the agent of the gateway. To change it, deploy a version to the agent in Configurations.

With CLI 0.1.14 or later, verdictan policy push changes the assignment through the agent. Use Deploy from the CLI for a connected gateway. Then check configuration sync status and send a test request.

verdictan gateway revert

verdictan gateway revert sends the rollback target that the last reload saved back to the running gateway, and checks it.

Usage

verdictan gateway revert --name <name> --gateway-url <url>

Options

Flag	Description
--name <name>	Mandatory definition name.
--gateway-url <url>	Mandatory base URL of the running gateway.

Examples

verdictan gateway revert --name local-example --gateway-url http://127.0.0.1:41002

The command prints reverted local-example. It then clears the rollback target, so you can revert one time after each reload. Without a rollback target, it stops with instance <name> has no rollback target.

verdictan gateway diff

verdictan gateway diff shows the config change of the last recorded operation of a definition: the previous and the active version and digest. It reads the state directory only. It does not contact the gateway.

Usage

verdictan gateway diff [--name <name>]

Options

--name <name> is the definition name. The default is verdictan-proxy.

Examples

verdictan gateway diff --name local-example

The output ends with Config version CHANGED or Config version unchanged. A definition without history prints No operations history for instance '<name>'.

verdictan gateway reconcile

verdictan gateway reconcile compares the active config of a running gateway with the config that its definition expects. The CLI finds the gateway at the listen address of the definition. It uses 127.0.0.1 for an all-interfaces address.

Usage

verdictan gateway reconcile (--name <name> | --all) [--apply-rollback] [--cancel]

Options

Flag	Description
--name <name>	Definition to reconcile.
--all	Reconcile all definitions.
--apply-rollback	When the gateway serves neither the expected config nor the rollback target, send the rollback target and check it.
--cancel	Clear the pending rollout plan of the definition. The command does not contact the gateway.

Examples

verdictan gateway reconcile --all
verdictan gateway reconcile --name local-example --apply-rollback

Each result has one of these outcomes:

Outcome	Meaning
healthy	The gateway serves the expected config.
rollback_verified	The gateway already serves the rollback target.
rollback_applied	The command sent the rollback target, and the gateway serves it.
drift_detected	The gateway serves a different config.
unreachable	The command could not read the gateway config.
cancelled	The command cleared the plan.

When a result is drift_detected or unreachable, the command stops with <n> instance(s) failed reconciliation.

verdictan gateway upgrade

verdictan gateway upgrade moves the service of a definition to a different verdictan binary. plan records the target. apply changes the service to the target binary and runs the health check. status shows the upgrade state. rollback changes the service back to the rollback binary.

The commands do not download or copy a binary. They rewrite the service file to start the binary at the path that you give, and restart the service. When no service is installed for the definition, or the service manager is manual, apply and rollback only record the change.

Usage

verdictan gateway upgrade plan --target-version <version> --binary-path <path> [OPTIONS]
verdictan gateway upgrade apply [OPTIONS]
verdictan gateway upgrade status [--name <name>]
verdictan gateway upgrade rollback [--name <name>]

Options

Flag	Applies to	Description
--name <name>	All	Definition name. The default is verdictan-proxy.
--target-version <version>	plan, apply	Version label of the new binary. Mandatory for plan.
--binary-path <path>	plan, apply	Path of the new binary. It must be a readable file. Mandatory for plan.
--rollback-version <version>, --rollback-binary-path <path>	plan, apply	Version and binary to go back to. The defaults are the active version and binary. A new definition has no active version, so give --rollback-version.
--health-command <command>	plan, apply	Shell command that apply runs after the change. A nonzero exit or a timeout marks the upgrade as failed.
--health-timeout-secs <n>	plan, apply	Timeout of the health command. The default is 30.
--service-manager <manual|launchd|systemd-user>	plan, apply	Service manager. The default is the manager of the installed service, or manual.
--config-sha256 <digest>	plan, apply	Config digest to record with the plan. The command does not check it.
--yes	plan, apply, rollback	Accepted. The commands do not prompt.

apply without plan flags runs the recorded plan. apply with plan flags builds a new plan and runs it. In that case, --target-version and --binary-path are mandatory.

Examples

verdictan gateway upgrade plan \
  --name local-example \
  --target-version "<new-version>" \
  --binary-path /absolute/path/to/new/verdictan \
  --rollback-version "<current-version>" \
  --health-command "curl -fsS http://127.0.0.1:41002/readyz"

verdictan gateway upgrade status --name local-example
verdictan gateway upgrade apply --name local-example
verdictan gateway upgrade status --name local-example --json

status shows the phase: planned, applying, succeeded, failed, or rolled_back. To go back to the rollback binary:

verdictan gateway upgrade rollback --name local-example

Limits and failure behavior

• The definition and service subcommands do not change the control plane. install does not create an agent, a gateway, or a configuration.
• reload and revert change only the running process, until a connected gateway pulls its assigned config again.
• The examples bind 127.0.0.1. Bind all interfaces only with a firewall, TLS, and application tokens.

Troubleshooting

Symptom	Cause	Fix
instance <name> does not exist	No definition has that name in the state directory.	Run verdictan gateway list, or pass the same --state-dir as create.
proxy config endpoint returned 401 Unauthorized	No admin token, or the gateway does not accept it.	Set VERDICTAN_API_TOKEN to the gateway runtime token.
proxy config endpoint returned 403 Forbidden	The token does not have gateways:read or gateways:deploy.	Use the gateway runtime token, or a token with the permission.
proxy reload endpoint returned 422	The gateway could not parse the YAML.	Run verdictan config validate and verdictan gateway check on the file.
instance <name> has no rollback target	No reload saved a target, or revert already used it.	Run reload with the earlier file.
service <name> did not reach the active state	The service process stopped at startup.	Read the log lines in the error, or the service log. Check credentials and flags.
unable to infer rollback version; pass --rollback-version	The definition has no active version.	Add --rollback-version.

Next steps

• verdictan gateway run: start a gateway in the current terminal.
• verdictan config validate: check the structure of a config before verdictan gateway check.
• Policy Lifecycle: check a config, and deploy it to the agent of a connected gateway.
• CLI Command Groups: see all CLI command groups.