Skip to main content

kt gateway

The kt gateway command group covers local supervisor definitions, runtime inspection, reload or revert workflows, OS-level service management, and a separate remote inventory view.

Preflight a runtime config​

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

kt gateway check --config policy-config.yaml

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

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

Local definitions and inventory​

Create a local supervisor definition​

kt 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 Keeptrusts control plane and does not start the process.

List local gateways​

kt gateway list

List remote gateways​

kt gateway list --remote

The local list reads supervisor state and needs no API token. --remote calls GET /v1/gateways and requires API authentication.

Inspection and runtime state​

Inspect a named gateway​

kt gateway inspect --name keeptrusts-proxy

Read a running gateway config endpoint​

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

Use --expect-version or --expect-sha256 when you want the command to fail on an unexpected runtime version or digest. If the runtime protects its admin endpoints, pass its admin bearer token with --api-token.

Diff local service state​

kt gateway diff --name keeptrusts-proxy

Reload a running gateway​

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

Reload reads the definition's configured policy paths unless --config-path is supplied. It records the current config as a rollback target, posts the new YAML, verifies the active version and digest, and attempts an automatic rollback if activation verification fails.

Revert a running gateway​

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

Revert requires the named local definition to have a saved rollback target from an earlier reload.

Reconcile gateway state​

kt gateway reconcile --name keeptrusts-proxy

Use --all to reconcile every known gateway, --apply-rollback to apply a pending rollback, or --cancel to cancel the pending action.

Service installation​

Install a local service​

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

If you install from policy-config.yaml, carry over the same runtime requirements as kt gateway run: bind the service to an agent and provide Keeptrusts API authentication.

Use --agent-id <id> for an exact binding or --agent-name <name> to resolve by name. Prefer KEEPTRUSTS_API_TOKEN over putting a runtime token directly in the command line. Installation targets a macOS launchd user service or Linux systemd user service.

The examples bind only to loopback. Choose an all-interface listener only when the host has deliberate ingress, firewall, TLS, and application-token controls.

Start, stop, status, and uninstall​

kt gateway start --name keeptrusts-proxy
kt gateway status --name keeptrusts-proxy
kt gateway stop --name keeptrusts-proxy
kt gateway uninstall --name keeptrusts-proxy

kt gateway status and kt gateway uninstall default to keeptrusts-proxy when --name is omitted, but including the name keeps scripts unambiguous.

Runtime binary upgrades​

Upgrade operations work on an existing local supervisor definition. Record a plan, apply it, inspect the result, or return to the recorded rollback binary:

TARGET_BINARY=/opt/keeptrusts/kt-next

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

kt gateway upgrade apply --name keeptrusts-proxy
kt gateway upgrade status --name keeptrusts-proxy --json
kt gateway upgrade rollback --name keeptrusts-proxy

apply can also take the plan fields directly. Optional health checks run after the service update; a failed check marks the upgrade failed. The current commands do not prompt before plan, apply, or rollback, so review the target and rollback paths before running them.

Next steps​