Connection Modes

SwiftServer speaks the Docker Engine API over the machine's existing SSH connection, and a request can take one of two routes to the daemon. The app probes both automatically on every connect — there is nothing to configure — but one route is strictly better, and getting onto it usually takes a single server-side change.

The two modes

Socket forwarding — recommended. The SSH server forwards each Docker Engine API request straight into the Docker socket (/var/run/docker.sock, or wherever the engine was detected). Nothing runs on the server for this: no extra processes, no sshd session slots consumed (which matters on servers with a low MaxSessions), and the lowest possible latency.

CLI tunnel — the automatic fallback. When socket forwarding is unavailable, SwiftServer runs docker system dial-stdio on the server and lets the docker CLI bridge to the daemon. Every feature works identically — containers, Compose, images, volumes, networks, logs, events all use the same Docker Engine API either way — but this route needs the docker CLI on the server and keeps a small resident footprint: at most three keep-alive bridge channels, reused across all monitoring requests rather than spawning a process per request. Live streams (events, container logs) use their own channels and are reclaimed the moment you leave the page.

Selection happens on every connect and retry: socket forwarding is tried first, and the CLI tunnel takes over only if it fails. Once the server allows socket forwarding, simply reconnecting upgrades the machine — there is no setting to flip.

Which mode am I on?

Two places tell you:

• The engine card on the Overview tab wears a transport badge. Green Socket: /var/run/docker.sock means socket forwarding; orange CLI Tunnel means the fallback.
• The Connection Log on the machine's Docker connection screen. On socket forwarding it reads Docker Engine reachable at /var/run/docker.sock. On the fallback it shows Effective socket failed: … — quoting the SSH server's actual refusal reason — followed by Docker Engine reachable through the pinned docker CLI tunnel.

Getting to socket forwarding

An orange badge means one of two independent gates is closed. Open both, reconnect, and the badge turns green.

1. Your SSH user can reach the Docker socket

sshd opens the socket as your login user, so the requirement is exactly the same as running docker on the server without sudo:

# Socket permissions and group — typically root:docker, 660
ls -l /var/run/docker.sock

# Is your login user in the docker group?
id

# If not, add it, then log out and back in
sudo usermod -aG docker <your-user>

2. sshd allows Unix-socket forwarding

This is a separate switch from Docker permissions. docker commands travel over SSH's exec channel; socket forwarding travels over SSH's forwarding channel — so docker ps can work perfectly while this gate stays closed. NAS and embedded systems in particular often ship with forwarding disabled. Check the live sshd configuration:

sudo sshd -T | grep -iE 'allowstreamlocalforwarding|disableforwarding'

The expected output is:

allowstreamlocalforwarding yes
disableforwarding no

If not, edit /etc/ssh/sshd_config:

AllowStreamLocalForwarding yes

make sure no DisableForwarding yes line remains, then restart sshd (sudo systemctl restart sshd, or your distribution's equivalent).

Verify

Back on the machine's Docker panel, tap Retry (or disconnect and reconnect). A green Socket: … badge means you're done. If it still says CLI Tunnel, the Effective socket failed: line in the Connection Log quotes the server's refusal reason — that's the remaining gate.

Is the CLI tunnel a problem?

No. It is the same panel, the same data, and the same operations, and the resident cost is capped at three reused keep-alive channels. If your server cannot offer socket forwarding at all, staying on the CLI tunnel loses you nothing beyond a little latency and a docker CLI dependency.