swarmexec

swarmexec › Docs › port-forward into the Swarm

port-forward into the Swarm_

A local port onto a container port nobody published.

port-forward (alias pf) — forward a local port

Bind a local TCP port and forward it to a port inside a container, without publishing that port on the cluster. The local port defaults to the remote one. Targeting a service forwards to exactly one of its tasks (the one the target resolves to), not across replicas. Bound to 127.0.0.1 by default. Press Ctrl-C to stop.

swarmexec port-forward [flags] <target> [local:]remote
FlagDefaultDescription
--address127.0.0.1local address to bind (loopback keeps the port off your network); any other address prints a warning that the port is reachable from your network
--node—node hint/override for container-id targets
--connect-timeout10stimeout for connecting to the agent
$ swarmexec port-forward db 5432 # localhost:5432 → container:5432 $ swarmexec pf web 9090:8080 # localhost:9090 → container:8080

How it works: the agent starts a short-lived sidecar container in the target's network namespace (the agent's own image, labelled swarmexec.role=port-forward) and carries every connection of the forward over it. After the last connection closes, the sidecar stays for about two minutes, so a browser reload or a reconnecting connection pool does not pay the container start again — a sidecar still there shortly after Ctrl-C is that pause, not a leak. The agent removes it on its own.