Protocol commands¶
Commands that reach a resource of each kind. They work the same on Linux and Windows except where noted. Global flags are in the CLI hub. Resource kinds:
ssh postgres mysql kubernetes tcp mcp llm web web-egress rdp
Previous db list, kube list, rdp list, tcp list and mcp list calls remain
aliases of the corresponding list command.
gdsgate ssh connect <target> [--exec [-- <ssh args>...]]¶
gdsgate ssh connect <target> remains a short call. A bare connect, config,
proxy or help remains a resource target, including with --exec and a payload after
--. The configuration command requires the full ssh config show path.
ssh proxy <resource> accepts delegation flags; SSH execution and remediation
flags apply to connection commands. ssh config show accepts the host pattern
and global configuration flags.
Requests an SSH access certificate for the resource named in <target>
(user@resource or resource). Authority issues it on Allow, and it is
cached. Use it to authorize before running native ssh.
With --exec, once the certificate is in place, the command runs
ssh <target> with the ProxyCommand passed inline; the ~/.ssh/config
fragment from ssh config show is not needed. On Linux
gdsgate is replaced by ssh; on Windows ssh runs as a child and its exit
code is passed on. Arguments after -- go to ssh unchanged:
| Argument | Default | Purpose |
|---|---|---|
<target> |
none | user@resource or just resource. |
--exec |
off | After issuing the certificate, run ssh <target>. |
-- <ssh args>... |
none | Trailing args forwarded to ssh. Requires --exec. |
user@ names the POSIX account the session runs as on the resource's host.
Only a backend that offers accounts accepts it; a jump host and a
connector-terminated backend in the default mode refuse it. When a backend
offers more than one account and policy allows more than one, omitting user@
is refused, and the refusal lists the accounts open to you. Host accounts are
Linux-only: a connector on Windows runs sessions as its own service account.
See Model A under a host account.
gdsgate ssh config show [<host_pattern>]¶
Prints an OpenSSH client-config fragment that routes native ssh through
gdsgate. The generated ProxyCommand carries this invocation's --config.
gdsgate --config ~/.gdsgate/client.toml ssh config show '*.gds' > ~/.gdsgate/ssh_config
# then, before the first Host block of ~/.ssh/config:
# Include ~/.gdsgate/ssh_config
Write the fragment to its own file with >; do not append to ~/.ssh/config.
Put the Include before the first Host block: OpenSSH uses the first value it
finds for each option. gdsgate up writes and includes
the same file.
| Argument | Default | Purpose |
|---|---|---|
<host_pattern> |
*.gds |
OpenSSH Host pattern the fragment matches. Aliases under the pattern become the gdsgate resource id. |
gdsgate ssh proxy <resource>¶
The SSH ProxyCommand transport: relays stdio to the resource's session over
the cluster. Native ssh runs it; do not run it by hand. stdout is the SSH byte
stream; logs go to stderr.
gdsgate db list¶
Lists database resources you can view.
gdsgate db login <resource>¶
Authorize a database resource: issues and caches a short-lived access certificate for it.
gdsgate db proxy <resource> [--listen <addr>]¶
Runs a localhost relay for psql / mysql. Each connection is authorized
separately (connect over the Database) and forwarded to the database.
| Flag | Default | Purpose |
|---|---|---|
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. :0 picks an ephemeral port (logged). |
gdsgate kube list¶
Lists Kubernetes cluster resources you can view.
gdsgate kube login <cluster> [--server <url>]¶
Prints a kubeconfig fragment that wires kubectl to gdsgate
through an exec credential plugin. Merge it into ~/.kube/config.
| Flag | Default | Purpose |
|---|---|---|
--server <url> |
http://127.0.0.1:6443 |
The API server URL kubectl should target: the gdsgate Kubernetes listener, with kube proxy running on this same address. |
The local relay speaks HTTP inside the authenticated gdsgate tunnel. The
connector separately verifies TLS when connecting to an HTTPS backend API.
Resident contexts are generated under ~/.gdsgate/kube/; load them in your
shell with source ~/.gdsgate/env, or pass a file with kubectl --kubeconfig.
The fragment carries this invocation's --config so the exec plugin
(kube credentials) runs against the same cluster.
gdsgate kube credentials <cluster>¶
The exec credential plugin for kubectl. Prints an ExecCredential
JSON on stdout. kubectl invokes it through the kubeconfig fragment
above; do not run it by hand.
gdsgate kube proxy <cluster> [--listen <addr>]¶
Runs a localhost relay for kubectl. Each connection is authorized (connect
over the KubernetesCluster) and forwarded to the connector, which proxies the
API server with impersonation. Each request is also authorized by
kubeRequest.
| Flag | Default | Purpose |
|---|---|---|
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. |
gdsgate rdp list¶
Lists the Windows desktops you may view.
gdsgate rdp proxy <resource> [--listen <addr>] [--exec [--client <program>]]¶
Localhost relay for an RDP client.
gdsgate rdp proxy win-app1 --listen 127.0.0.1:3390 &
mstsc /v:127.0.0.1:3390 # or: xfreerdp /v:127.0.0.1:3390
--exec starts the client and exits when it exits. The client is mstsc on
Windows and xfreerdp on Linux unless --client names another; both take the
address as /v:.
| Flag | Default | Purpose |
|---|---|---|
--windows-user <account> |
unset | The Windows account to open the session as, where the desktop offers more than one. |
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. |
--exec |
off | Start an RDP client against the listener and exit with it. |
--client <program> |
mstsc on Windows, xfreerdp on Linux |
The client --exec starts. Requires --exec. |
The listener prints a name and password; the desktop admits no other. The pair is valid until the command exits, so the client can reconnect with it. The listener carries one session at a time: a second connection while one is live is refused with a message. A reconnect after the old connection closed is accepted.
--exec passes the address and name on the client's command line and the
password through FreeRDP's FREERDP_ASKPASS helper (FreeRDP 3.8 or newer).
mstsc gets the address only; type the name and password.
The pair is not a Windows account. The backend decides which Windows account the session logs in as; see below.
The listener's TLS certificate is issued per session for the bound address and
signed by this machine's local root, the one gdsgate web trust prints. Install
that root once to stop the RDP client's certificate warning. A client started by
--exec is given the digest of that session's certificate and needs neither
the root nor a confirmation.
Access is decided by policy (connect over RdpHost). The session appears in
gdsgate sessions list, can be killed, and every open and close is audited.
The connector's configuration decides what happens inside the session:
windows_user set |
windows_user unset |
|
|---|---|---|
| Who logs in to Windows | the connector, with the password credential_file names |
you, with your own credentials |
| What the gateway sees | the desktop, which it draws again for your client | bytes it does not read |
| Audit close row | painted, input_events |
bytes_up, bytes_down |
With windows_user set, the session is recorded as <session>.rdp and
delivered like other recordings; gdsgate authority recordings list shows it.
With windows_user unset, the session is not recorded.
Neither mode controls the clipboard, redirected drives or printers.
gdsgate tcp list¶
Lists raw-TCP resources you can view (Redis, internal HTTP, …).
gdsgate tcp proxy <resource> [--listen <addr>]¶
Localhost relay for any TCP client.
| Flag | Default | Purpose |
|---|---|---|
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. |
gdsgate mcp list¶
Lists MCP-server resources you can view.
gdsgate mcp proxy <resource> [--listen <addr>]¶
Localhost MCP endpoint. The connector checks each tools/call,
resources/read and prompts/get against policy before it reaches the backend,
and filters tools/list to the tools you may view (viewTools). Every call is
audited.
The endpoint accepts two client transports:
- Streamable HTTP, protocol revision
2026-07-28: give the client the URL. - stdio, for a client that starts a program: use
gdsgate mcp bridge.
gdsgate mcp proxy tools-mcp --listen 127.0.0.1:8765 &
# MCP client over Streamable HTTP: http://127.0.0.1:8765/
# MCP client over stdio: command `gdsgate mcp bridge 127.0.0.1:8765`
The endpoint refuses a request with an Origin header or with a Host other
than its own loopback address. GET and DELETE get 405. An
Mcp-Session-Id from the client is ignored and not echoed.
| Flag | Default | Purpose |
|---|---|---|
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. |
gdsgate mcp bridge <endpoint>¶
Connects an MCP client that can only start a program to an endpoint, over
stdin and stdout. <endpoint> is the host:port that gdsgate mcp proxy
printed.
// in the client's MCP server configuration
{
"command": "gdsgate",
"args": ["mcp", "bridge", "127.0.0.1:8765"]
}
The bridge only relays bytes. Requests through it are authorized at the connector.
gdsgate web proxy <resource> [--listen <addr>]¶
Localhost relay onto an HTTP(S) resource: a kind = "web" application, or the
one kind = "web-egress" way out named on your grant. There is no web ls:
gdsgate resources list shows web resources beside every other kind.
For an application, the connector proxies each request under the application's
own name; its Host, cookies, redirects and links use that name. For a
web-egress resource the listener is a forward proxy (absolute target or
CONNECT): set it as the client's proxy
(curl -x http://127.0.0.1:<port> https://github.com). gdsgate delegations create --exec
sets it for a program; see
Endpoints: what the program is given.
| Flag | Default | Purpose |
|---|---|---|
--listen <addr> |
127.0.0.1:0 |
Local host:port to bind. |
See Configuration → The web lane and Policy → HTTP(S) application routes.
gdsgate web trust [--quiet]¶
Prints the certificate root the resident client signs an application's own
domain with, when [client].intercept_names and
a catalogued native_name agree on one. See
Resident client → An application's own name.
The certificate goes to stdout and the explanation to stderr:
gdsgate web trust --quiet > gdsgate-local-root.crt writes a plain file.
Creates a root for this machine if there is none. Installs nothing: it prints the install and undo commands for this platform.
| Platform | Printed commands |
|---|---|
| Linux | Debian/Ubuntu and Fedora/RHEL system store, Chrome/Chromium NSS database, Firefox |
| Windows | certutil -user -addstore Root for Edge, Chrome and other programs using the Windows store (Windows asks for confirmation in a dialog); Firefox. Undo: the certutil -user -delstore Root command it prints, which names the root by its full common name |
Install the printed certificate. Do not install the file under ~/.gdsgate: it
also holds the private key.
| Flag | Default | Purpose |
|---|---|---|
--quiet |
off | Print only the certificate, with no explanation on stderr. |
list ls login proxy
list ls login credentials proxy
list ls proxy
list ls proxy bridge
proxy trust