# gdsgate

> gdsgate is a PAM/ZTNA platform for controlled access by people, workloads and AI agents to infrastructure. It combines identity-based authorization, short-lived access credentials, audit and session recording.

Supported resources include SSH hosts, databases, Kubernetes clusters, web applications, MCP servers, model services, Windows desktops and TCP services. One executable provides the Authority control plane, Proxy gateways, resource Connectors, access clients and Agent hosts.

This index describes 0.11.x, including v0.11.0-rc.13. Use documentation matching `gdsgate --version`. The 0.10.x edition retains its own commands and procedures; do not combine instructions from different editions.

## Versions and commands

- [Documentation versions](https://gate.gds.dev/docs/0.11/versions/): choose the matching edition, with separate navigation and search; documentation `latest` is independent of the container `:latest` tag
- [0.10.x documentation](https://gate.gds.dev/docs/0.10/): commands and deployment procedures for an existing 0.10 installation
- [Changes in 0.11.x](https://gate.gds.dev/docs/0.11/changes-0.11/): entity/action commands, legacy aliases, configuration selection, enrollment, publication and reload
- [CLI reference](https://gate.gds.dev/docs/0.11/cli/): command families and primary entity/action paths
- [Configuration selection](https://gate.gds.dev/docs/0.11/cli/#configuration-selection): `gdsgate contexts use PATH` selects an existing file; `--config PATH` overrides that selection for one invocation; server commands use installed role configurations
- [External route commands](https://gate.gds.dev/docs/0.11/cli/egress/): rc.13 experimental transparent TCP and native UDP egress on Linux/Windows, including HTTP/3, with full/selective routing and separate destination permissions; UDP uses udpConnect/POL-0209 and action-bound single-use step-up grants; client routing editor; find web-egress resource identifiers with resources list, choose gate/direct/block actions; common tables/pager and terminal colours, UDP Proxy endpoints only in wide/JSON details, JSON route rows, first-match TCP/UDP rules, reload without restart, selected-address kill switch, recorded-upstream DNS recovery and explicit protection release; domain/CIDR rules with an identical action avoid local DNS, conflicting actions still require address-based selection; use a matching rc.13 binary
- [Client connection and login](https://gate.gds.dev/docs/0.11/cli/client/): `connect`, multiple clusters, OIDC login, identity renewal and Resident commands
- [Egress connection lifetime](https://gate.gds.dev/docs/0.11/cli/egress/#connection-lifetime): compatible components renew ordinary key-bound user CONNECT channels with fresh proof and Authority admission/destination checks, preserving the backend socket; legacy/delegated/inspected channels retain original expiry; policy edits apply at the next authorization decision, explicit session termination closes active channels
- [Resident client](https://gate.gds.dev/docs/0.11/resident-client/): rc.13 reuses gateway transports, separates control RPCs from session streams and retains per-session access checks and credential deadlines; catalog/certificate responses and gateway connection setup have separate 20-second limits, failed requests release cached transports without replaying uncertain issuance or closing established streams; atomic private credential records prevent mixed key/certificate writes, inconsistent legacy pairs trigger normal reissuance before proof of possession; transparent TCP preserves established connections across pauses longer than one minute without changing session or shutdown deadlines
- [HA configuration](https://gate.gds.dev/docs/0.11/configuration/ha/): rc.13 defaults to a 6-second lease and 1-second renewal, reserves PostgreSQL heartbeat and fresh discovery capacity, keeps same-term heartbeat renewal independent of slow tunnel-route transactions and observes live foreign leaders without write locks; epoch replacement and release still wait for admitted writers; limits idle writer transactions to five seconds without changing separate audit-reader settings and releases fenced leadership on normal Unix stop; verified Authority membership additions with unchanged integrity material preserve admission and pending audited decisions; explicit settings remain unchanged

Administrative paths use an entity followed by an action, for example `gdsgate authority resources list` and `gdsgate authority nodes list`. Client catalog access uses `gdsgate resources list`. Old spellings remain aliases. Configuration selection does not create an identity or grant administrative permissions.

## Configuration and initial setup

Use the schema and role reference for field names and defaults. Select the security profile (`dev`, `pilot` or `production`), then validate the actual file and role before starting a service.

```sh
gdsgate config schema --role authority > authority.schema.json
gdsgate config check authority.toml --role authority --profile pilot --json
```

`config check` exits `0` with no findings, `1` for errors and `2` for warnings only. `doctor --role ROLE` checks the selected component and its state; it is separate from configuration validation.

- [Configuration JSON Schema](https://gate.gds.dev/docs/0.11/reference/config.schema.json): field types, role applicability and profile requirements
- [Loading and global settings](https://gate.gds.dev/docs/0.11/configuration/overview/): file selection, environment overrides and secret references
- [Database connection pools](https://gate.gds.dev/docs/0.11/configuration/overview/#store-pools): rc.13 per-process main/discovery/readiness capacity, minimum connections, acquisition and retirement timeouts; PostgreSQL only, defaults 28/8/2, requires Authority restart, dedicated heartbeat and audit connections retain their limits
- [Security profiles](https://gate.gds.dev/docs/0.11/configuration/profiles/): required settings, startup refusals and warnings by role
- [Setup](https://gate.gds.dev/docs/0.11/cli/setup/): `setup prepare`, `setup --tui` on fresh hosts, shared CLI defaults, basic/advanced settings, saved bundles, apply, change and restore
- [Enrollment and re-join](https://gate.gds.dev/docs/0.11/cli/join/): node roles, trust confirmation, saved identity, expired credentials and replacement configuration
- [Services](https://gate.gds.dev/docs/0.11/cli/service/): install, start, reload and uninstall role services on supported platforms
- [Per-role recipes](https://gate.gds.dev/docs/0.11/configuration/recipes/#per-role-recipes): Authority, Proxy, Connector, client and combined mode examples
- [OIDC](https://gate.gds.dev/docs/0.11/oidc/): provider profiles, device polling, profile distribution, user identifiers and Kubernetes identity mapping
- [Security configuration](https://gate.gds.dev/docs/0.11/configuration/security/): keyrings, MFA, certificate rotation and integrity settings

In `setup --tui`, Enter on the step rail focuses the selected step; another Enter edits its selected field. Editing keys replace navigation commands in the footer. Role changes and advanced-field visibility keep the selection on a displayed field. The setup wizard previews configuration before Apply. Supported runtime changes use role reload; a failed reload does not trigger a restart. Restore writes files only and requires explicit runtime application. Connector and client commands shown for other hosts must be run on those hosts.

For new Authority setup, a PostgreSQL store enables HA and keyring synchronization even in the dev profile or a single-host Authority + Proxy deployment. It starts with one member. The Authority bind is this node's own address, independent of the database host and public gateway/LB. Automatic selection requires an IPv4 assigned to exactly one active local interface; DNS, external LB/NAT addresses, IPv6 and saved bundles require an explicit bind. Explicit loopback is limited to one host. Existing configuration files retain their settings on upgrade. See [Authority address selection](https://gate.gds.dev/docs/0.11/cli/setup/#authority-addresses).

## HA components and deployment topologies

Choose the topology independently of the packaging. Compose Authority HA, Proxy HA and Connector connectivity using the component guides, then follow the matching native or container deployment recipe.

- [HA overview](https://gate.gds.dev/docs/0.11/ha/): routing, availability, shared dependencies and topology choices
- [Authority HA](https://gate.gds.dev/docs/0.11/ha/authority/): direct failover or L4 load balancer, shared store, peers, readiness and leadership
- [Authority bootstrap](https://gate.gds.dev/docs/0.11/ha/bootstrap/): admit additional Authorities, synchronize keyrings and recover protected state
- [Proxy HA](https://gate.gds.dev/docs/0.11/ha/proxy/): enrollment identities, private peering and public L4 entry; upgraded peers preserve queued replies on normal EOF and retain forced termination under backpressure
- [Connector for HA Proxy pools](https://gate.gds.dev/docs/0.11/ha/connector/): verified tunnels, catalog admission, renewal and central recording
- [One Linux host](https://gate.gds.dev/docs/0.11/deploy/vps/): native Authority and Proxy deployment
- [Separate hosts](https://gate.gds.dev/docs/0.11/deploy/split/): internal Authority, separate Proxy and Connector routes
- [Docker Compose](https://gate.gds.dev/docs/0.11/deploy/compose/): services, persistent state and configuration
- [HA with direct Authority failover](https://gate.gds.dev/docs/0.11/deploy/ha-without-authority-lb/): public LB to Proxy HA; Authority HA without a private LB
- [HA with an Authority load balancer](https://gate.gds.dev/docs/0.11/deploy/ha-with-authority-lb/): separate Authority and Proxy routing, with native and container instructions
- [Kubernetes deployment](https://gate.gds.dev/docs/0.11/deploy/kubernetes/): chart, manifests, Services and an in-cluster Connector with ServiceAccount credentials
- [Docker Swarm](https://gate.gds.dev/docs/0.11/deploy/swarm/): persistent state, secrets, published ports, upgrade and rollback
- [Certificates](https://gate.gds.dev/docs/0.11/deploy/certificates/): IP-only deployments, TLS names, trust anchors, private keys and renewal
- [Quickstart](https://gate.gds.dev/docs/0.11/quickstart/): select a deployment, profile and route

## Agents

- [Agent host](https://gate.gds.dev/docs/0.11/agent-host/): run Authority-declared agents in cages under their own identities on Linux; resource sessions use Proxy, published faces use an outbound reverse tunnel
- [Agent host configuration](https://gate.gds.dev/docs/0.11/configuration/agent-host/): host identity, publication scope, cage and runtime settings
- [Delegated agents](https://gate.gds.dev/docs/0.11/ai-agents/): run a program under a time-limited part of a person's access

## Resources, discovery and access controls

Rc.12 changes keep catalog, HTTP authorization and fresh Proxy readiness responsive during concurrent session and audit work. Ordinary polling of unchanged Authority keyrings, node capability renewal, discovered-resource publication and background audit/lease processing run outside the shared control-plane service lock during storage waits; changed keyring material retains exclusive installation and verification failures withdraw admission. Replies recheck admission; resource/evidence writes remain atomic and audit commits retain fencing and replay detection. Peer discovery validates the requested resource without rechecking unrelated Connector resources and has reserved read-only database capacity and a separate Authority transport during certificate bursts. MFA, approval and step-up facts are read together with signature and single-use checks preserved. Catalog policy CPU work runs outside the Authority service lock with bounded concurrency and rejects publication after policy, identity or admission changes. Peer stream setup, backend admission and close monitoring have separate bounded waits; their total can exceed three seconds. Catalog visibility, connection authorization, a serving Connector and protocol controls are distinct checks. Discovery does not install a Connector on each target or grant access by itself. A catalog row alone does not mean a resource is currently served.

- [Catalog configuration](https://gate.gds.dev/docs/0.11/configuration/catalog/): `[catalog]`, publication modes, import rules, attributes and Authority-owned scopes
- [Resource administration](https://gate.gds.dev/docs/0.11/admin/resources/): manual and automatic publication, node identities and resource lifecycle
- [Discovery sources](https://gate.gds.dev/docs/0.11/configuration/discovery-sources/): `connector.discovery_sources`, Kubernetes and PostgreSQL discovery, optional parent connections and compatibility
- [Kubernetes setup helper](https://gate.gds.dev/docs/0.11/cli/setup/#gdsgate-setup-kubernetes-configure): `setup kubernetes configure ID --purpose api|discovery|both` writes backend/source declarations; deploy the resulting file as the Connector configuration
- [Connector backends](https://gate.gds.dev/docs/0.11/configuration/connector/): protocol endpoints, SSH onward authentication, PostgreSQL `session_role`, guarded passthrough, SQL policy and Kubernetes impersonation
- [Policy configuration](https://gate.gds.dev/docs/0.11/configuration/policy/): authorization vocabulary, policies and role mappings
- [Capsule integration](https://gate.gds.dev/docs/0.11/integrations/capsule/): optional tenant filtering, collection permissions, membership freshness and policy checks

Do not assume that a discovered database has SQL enforcement or service-account login enabled. Check the source and backend settings. PostgreSQL `session_role` and `enforce_query_categories` have protocol-specific requirements; MySQL passthrough does not provide those PostgreSQL controls.

## Resident, reload and operations

Rc.12 client gateway connections use HTTP/2 keepalive with a 15-second interval and 10-second acknowledgement timeout, including idle connections. Complete connection setup, including TLS and waiting for shared transport initialization, is bounded to 20 seconds, so a silent handshake cannot indefinitely stop catalog refresh or access preparation. Silent transport failure ends the affected connection so later calls can reconnect; application requests are not replayed and permission expiry remains unchanged. Active session transport errors and their underlying causes are reported in client diagnostics. Restart a running Resident after replacing the binary to use this behavior; these are protocol liveness checks, not an application payload idle timeout.

- [macOS transparent access and DNS](https://gate.gds.dev/docs/0.11/resident-client/#macos-system-dns): experimental utun42 and per-UID TCP/UDP egress, ordinary-user resident plus root client-net --owner-uid broker; compatible minimal PF hook prepared by the helper; own PF enable reference acquired only with interactive approval or explicit --pf-enable yes; ask/no preserve state without approval, existing approved reference reused; stateless surrounding policy required; temporary supplemental DNS, prefix guards and reload; original DNS is auto-discovered or explicitly overridden by dns_upstream for direct TCP DNS forwarding, ordinary domain gate resolves at the Connector; requires the rc.13 client; the earlier DNS-only archive lacks this backend; ICMP and other IP protocols are outside egress/kill-switch scope


- [Proxy Watch lifecycle](https://gate.gds.dev/docs/0.11/ha/proxy/#watch-current-state): rc.13 uses current trust/live-identity snapshots followed by newer changes; migration m0093; older Authority retains legacy replay; upgraded Authority bounds replay pages to 256 events; audit history is separate and preserved; readiness failures withdraw new connections without forcing established streams closed; transient session renewals retry within the existing lease deadline

- [Resident client](https://gate.gds.dev/docs/0.11/resident-client/): basic/direct/transparent access, port offsets, names, Linux service privileges, Windows helper and local OS-owner isolation
- [Configuration reload](https://gate.gds.dev/docs/0.11/cli/reload/): supported settings per server role, acknowledgment, refused changes and restart requirements; without `--role`, `gdsgate reload` targets the Resident
- [Client status](https://gate.gds.dev/docs/0.11/cli/client/#gdsgate-status---json---explain): `status --explain`, serving state, local publication and remedies
- [Listing pages and terminal viewer](https://gate.gds.dev/docs/0.11/cli/#listing-pages): `--limit`, `--cursor`, `--all`, search in loaded rows, `--no-pager`, JSON and colours
- [Diagnostics](https://gate.gds.dev/docs/0.11/cli/diagnostics/#gdsgate-doctor): role-aware doctor, findings and remedies
- [Health and metrics](https://gate.gds.dev/docs/0.11/operations/health/): readiness, metrics and component diagnostics
- [Audit](https://gate.gds.dev/docs/0.11/operations/audit/): full integrity verification, temporary storage, queued events, recovery progress, external anchors and exports; rc.13 adds bounded incremental checks with a private trusted prefix and separate full/tail results
- [Audit configuration](https://gate.gds.dev/docs/0.11/configuration/operations/#audit): full `verify_interval_secs` (300) and rc.13 `incremental_verify_interval_secs` (5); incremental startup requires full bootstrap; both zero disables automatic verification
- [Session format activation](https://gate.gds.dev/docs/0.11/cli/administration/#gdsgate-authority-migrate): rc.13 `authority store migrate --sessions` requires every Authority upgraded and legacy sessions drained; schema migration alone keeps the legacy session format
- [Administrative operations](https://gate.gds.dev/docs/0.11/cli/operations/): sessions, audit and recording commands
- [What a change affects](https://gate.gds.dev/docs/0.11/deploy/change/): affected files, identities, reload or restart, failure symptoms and validation

`contexts use PATH` reloads a running Resident before saving a successful selection. Server reload uses the installed role configuration, not the client context. Reload cannot load a replacement executable. Use JSON for scripts; text tables and terminal paging are presentation formats. Audit and recording listings retain a default total of 50 rows; `--all` reads the remaining pages. The rc.13 client fetches `authority recordings show SESSION_UID` directly from central storage without a history listing; disk-only casts remain on the Connector and event file URIs are not opened locally.

## Releases and upgrades

- [Release history](https://gate.gds.dev/docs/0.11/changelog/history/): user-visible additions, behavior changes, fixes and required upgrade actions; rc.13 covers external TCP/UDP routing, experimental macOS access, database pool settings, client recovery, HA responsiveness, audit checks, recording transfer and authentication cryptography security updates; full schema/session activation and upgrade-order requirements remain explicit
- [rc.11 to rc.13](https://gate.gds.dev/docs/0.11/changelog/upgrade-guide/#to-v0110-rc13): Authority-first rolling upgrade, schema and optional session-format activation, recording rollback limits, client/helper restarts, HA defaults and audit verification
- [rc.10 to rc.11](https://gate.gds.dev/docs/0.11/changelog/upgrade-guide/#to-v0110-rc11): cryptographic and Unix I/O safety fixes, rolling restarts, Linux client unit installation, Windows helper update, verification and rollback
- [Upgrade guide](https://gate.gds.dev/docs/0.11/changelog/upgrade-guide/): signed artifacts, release channels, version migrations, paired state/key backups and recovery boundaries