Managed Mode

Managed mode (kt run --managed) starts the gateway with automatic configuration polling from the Keeptrusts API. This is the recommended mode for production deployments where configurations are managed centrally.

Use this page when

• You are deploying a Keeptrusts gateway that should pull configuration from the control-plane API automatically.
• You need the kt run --managed flags, environment variables, or Docker deployment pattern.
• You want gateways to hot-reload policy changes without manual restarts.

For the rest of the public gateway command surface, including local kt gateway run, control-plane reconciliation, and service-management commands, see CLI Command Groups.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Usage

kt run --managed [OPTIONS]

Options

Flag	Env Var	Description
--gateway-id <id>	KEEPTRUSTS_GATEWAY_ID	Unique identifier for this gateway instance
--api-url <url>	KEEPTRUSTS_API_URL	Keeptrusts API URL
--gateway-token <token>	KEEPTRUSTS_GATEWAY_TOKEN	Scoped gateway token
--listen <host:port>	—	Listen address (default: 0.0.0.0:8080)
--upstream <url>	KEEPTRUSTS_UPSTREAM_URL	Debug-only upstream override; managed gateways should normally use their assigned config
--poll-interval <seconds>	—	Config poll interval (default: 30)

Examples

Basic Managed Gateway

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_GATEWAY_TOKEN="kt_your_scoped_token"
export KEEPTRUSTS_GATEWAY_ID="proxy_production_01"
export OPENAI_API_KEY="sk-your-openai-key"

kt run --managed \
  --listen 0.0.0.0:41002

The managed configuration assigned to the gateway should define providers.targets[]. The runtime only needs the provider secret through secret_key_ref, secret_key_ref, or the config-variable resolver.

Docker Deployment

docker run -d \
  --name keeptrusts-gateway \
  -p 8080:8080 \
  -e KEEPTRUSTS_API_URL="https://api.keeptrusts.com" \
  -e KEEPTRUSTS_GATEWAY_TOKEN="kt_your_scoped_token" \
  -e KEEPTRUSTS_GATEWAY_ID="proxy_production_01" \
  -e OPENAI_API_KEY="sk-your-openai-key" \
  keeptrusts/kt:latest run --managed

How It Works

1. On startup, the gateway fetches its configuration from the API
2. Every poll-interval seconds, it checks for updates
3. When a new version is available (e.g., from a rollout), it hot-reloads automatically
4. The gateway reports its running version and health status back to the API

Updating Managed Configurations

Use the Console or API to push new configurations:

# Via API: trigger rollout
curl -X POST https://api.keeptrusts.com/v1/admin/configurations/rollout \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gateway_ids": ["proxy_production_01"], "version": "0.3.0"}'

The managed gateway will pick up the change on its next poll cycle and hot-reload without downtime.

Monitoring Managed Gateways

Check gateway status from the API:

curl -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  https://api.keeptrusts.com/v1/admin/configurations

{
  "items": [
    {
      "gateway_id": "proxy_production_01",
      "status": "healthy",
      "running_version": "0.3.0",
      "last_seen_at": "2026-03-20T12:05:00Z"
    }
  ]
}

For AI systems

• Canonical terms: managed mode, kt run --managed, gateway polling, hot-reload, config rollout.
• Flags: --gateway-id, --api-url, --api-token, --listen, --poll-interval, --upstream.
• Environment variables: KEEPTRUSTS_GATEWAY_ID, KEEPTRUSTS_API_URL, KEEPTRUSTS_GATEWAY_TOKEN, KEEPTRUSTS_UPSTREAM_URL.
• API endpoint used: GET /v1/admin/configurations/gateways/:id/runtime-state.
• Related pages: kt gateway run, CLI Command Groups.

For engineers

• Prerequisites: A registered gateway in the console with a valid gateway_id, a scoped gateway token with configurations:read permission, and the upstream provider credentials available as environment variables.
• Validate: After starting, confirm the gateway reports healthy status via GET /v1/admin/configurations. Check Docker logs for config loaded and the expected running_version.
• Troubleshooting: If the gateway exits with a connection error, confirm KEEPTRUSTS_API_URL is reachable from the container. If config never updates, check poll-interval and that a new config version has been rolled out.

For leaders

• Managed mode is the recommended production deployment model — it ensures gateways always run the latest approved policy configuration without manual intervention.
• Rollouts can be staged: push a new config version to a subset of gateways, validate, then expand.
• Operational risk: If the API is unreachable, gateways continue running their last-known config. No requests are dropped due to a transient control-plane outage.
• Cost: Polling adds negligible API load (one lightweight GET per gateway per poll interval, default 30s).

Next steps

• kt gateway run — Local gateway startup and configuration reference
• Multi-Provider Fallback — Configure provider failover in managed configs
• CLI Command Groups — Full gateway lifecycle surface
• CLI overview