Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker Context: Managing Multiple Daemons, Remote SSH, and TLS Sockets

One CLI, many daemons: ssh:// and TLS contexts, the bind mounts that point at the remote host, and why port 2375 without TLS is root access.

~5 min readDocker
#Docker#CLI#Remote Management
3D illustration of a local Docker CLI switching between a unix socket and remote daemon endpoints over SSH tunnels

Quick Summary

A Docker context is a named endpoint for the Docker API: which daemon the CLI talks to, and how. The default one is the local Unix socket. A context can point at a remote daemon over SSH, at a TCP socket with TLS client certificates, at a rootless socket, or at Docker Desktop's VM. docker context use prod switches every later command; docker --context prod ps switches for one.

The point is to stop juggling DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH environment variables by hand, and to make the target of a destructive command explicit. Contexts are also what docker compose v2 and docker buildx read, so one switch moves the whole toolchain.

Two facts are worth internalising. First, a context changes where images, volumes and bind mounts live: -v /srv/data:/data refers to the remote host's /srv/data, not yours. Second, an exposed daemon socket without TLS is root access for anyone who can reach the port — port 2375 open on a public interface is a compromised host waiting for a scanner.

Basic syntax and query signatures

bash
# SSH: the simplest remote context (needs a Docker socket on the server) docker context create staging --docker "host=ssh://deploy@10.0.0.7" docker context create prod --docker "host=ssh://deploy@prod.example.com" \ --description "production swarm manager" docker context ls docker context use staging docker ps # now runs against 10.0.0.7 docker --context prod ps # one-off # TLS: mutual authentication against a daemon exposing 2376 docker context create secure \ --docker "host=tcp://10.0.0.9:2376,ca=$PWD/ca.pem,cert=$PWD/cert.pem,key=$PWD/key.pem" docker --context secure version # rootless daemon docker context create rootless --docker "host=unix://$XDG_RUNTIME_DIR/docker.sock" docker context inspect prod --format '{{json .Endpoints.docker}}' docker context rm staging docker context use default
bash
# the daemon side of a TLS endpoint dockerd \ -H unix:///var/run/docker.sock \ -H tcp://0.0.0.0:2376 \ --tlsverify \ --tlscacert /etc/docker/ca.pem \ --tlscert /etc/docker/server-cert.pem \ --tlskey /etc/docker/server-key.pem
json
// ~/.docker/config.json { "currentContext": "staging", "contexts": {} }

Key comparison table

EndpointURL formClient authBest for
Local socketunix:///var/run/docker.sockFile permissionsDefault, single host
SSHssh://user@hostSSH key or agentRemote hosts with SSH already set up
TCP + TLStcp://host:2376 + ca/cert/keyMutual TLSAutomation, CI, multiple operators
TCP plaintcp://host:2375NoneNever on a reachable network
Rootless socketunix:///run/user/1000/docker.sockFile permissionsRootless daemon
Docker Desktopunix:///Users/.../docker.sockPer-userDesktop VMs
SettingScopePrecedence
-H / --host flagOne commandHighest; overrides any context
--context flagOne commandNext
DOCKER_CONTEXTShell or processNext
currentContext in config.jsonUserUsed when nothing above is set
DOCKER_HOSTShell or processLegacy; bypasses contexts
ActionLocal effectRemote effect
docker build .Build context uploaded from hereImage stored on the remote daemon
docker run -v /srv/x:/xPath on this machinePath on the remote host
docker pullImage cached hereImage cached there
docker cpBetween local filesystem and containerTransfers over the API
docker context useChanges the CLI targetNothing on the daemon

Practical edge cases and deep dives

1. Bind mounts and volumes are the remote host's

bash
docker --context prod run --rm -v /srv/app/config:/config alpine cat /config/app.yml

That reads /srv/app/config/app.yml on the production host. Run the same command locally and you read your laptop's path — or get an empty directory, because Docker creates missing bind-mount sources as root-owned empty directories. This is the most common way a "works on staging" change breaks production: the compose file is identical, the file it mounts is not.

The same applies to docker build: the build context is uploaded from the machine running the CLI, so a .dockerignore mistake ships local secrets to the remote daemon's builder.

2. SSH contexts need the socket, not just a login

code
docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Over an SSH context this usually means the SSH login works and the socket is not writable by that user. Add the user to the docker group on the server (usermod -aG docker deploy, then re-login), or use a user with socket access. Note what that grants: membership in docker is root-equivalent. A dedicated deploy user with an SSH key restricted by command= and from= is the safer arrangement.

SSH contexts also inherit your ~/.ssh/config, so host aliases, jump hosts and keys work. A failing context with a host key mismatch shows up as ssh: handshake failed: knownhosts: key mismatch — the fix is on the SSH side, not in Docker.

3. Plain TCP is a remote root shell

bash
dockerd -H tcp://0.0.0.0:2375 # never

Anyone who can reach 2375 can create a container with -v /:/host --privileged and own the machine. Internet scanners find it within hours. If a TCP endpoint is genuinely needed, use 2376 with --tlsverify and client certificates, bind it to a private interface, and put a firewall rule in front of it. SSH contexts avoid exposing a port at all and are the better default for a small team.

Generating the certificates is a one-time exercise: a CA, a server certificate with the host's IP or DNS name in the SAN, and a client certificate. docker context create with ca, cert and key enables verification; adding skip-tls-verify disables it, which defeats the purpose.

4. Compose and buildx follow the context, with caveats

Docker Compose v2 uses the active context. Compose v1 (docker-compose) only reads DOCKER_HOST, so on a machine with both installed the same file can target different daemons:

bash
docker context use prod docker compose up -d # prod docker-compose up -d # whatever DOCKER_HOST says, often local

Set DOCKER_CONTEXT=prod in the shell as well, or remove v1. Buildx keeps a builder per context name, so switching context may switch builder implementation; docker buildx ls shows which builder is current and which context it belongs to.

5. Removing a context in use

unable to remove context "staging": context is in use

That error means it is the current context (docker context use default first) or it is the endpoint of an existing builder (docker buildx rm). Contexts are just directories under ~/.docker/contexts/meta/; deleting them by hand leaves a broken currentContext entry in config.json, which surfaces as:

unable to resolve docker endpoint: context "staging" does not exist

Use docker context use default and docker context rm rather than editing files, and if you do edit config.json, make sure currentContext names a context that exists.

6. Checking where a command will land before running it

bash
docker context show # active context name docker --context prod system info --format '{{.Name}} {{.OperatingSystem}}' docker context ls --format '{{.Name}} {{.DockerEndpoint}} {{.Current}}'

Put docker context show in the prompt of the shell you use for operations, or wrap destructive commands in a script that refuses to run unless $(docker context show) matches an expected value. The cost of the check is one second; the cost of docker system prune --volumes on the wrong daemon is a restore from backup.

Common mistakes and runtime errors

Error or symptomCauseFix
Cannot connect to the Docker daemon at tcp://...:2376Endpoint down, firewall, or wrong portCheck docker context inspect, test the port
permission denied ... docker.sock over SSHRemote user not in docker groupAdd to the group, re-login
unable to resolve docker endpoint: context "x" does not existStale currentContextdocker context use default
context is in use on removalActive context or a buildx builderSwitch context, remove the builder
Files missing in a bind mountPath exists on the local host onlyUse the remote path, or copy data
docker compose hits the wrong daemonCompose v1 ignores contextsDOCKER_CONTEXT, or remove v1
TLS handshake failureCert SAN does not match the hostReissue the server cert with the right SAN
x509: certificate signed by unknown authorityClient CA does not match the server'sUse the same CA for both sides
Slow docker build over SSHLarge context uploaded each time.dockerignore, or build on the remote host
docker exec succeeds but logs are elsewhereFollowed a context switch mid-sessionCheck docker context show

A good habit to close with: name contexts by environment, not by hostname (prod, staging, lab), set DOCKER_CONTEXT explicitly in CI rather than relying on a saved default, and make the current context visible in whatever terminal you use for production work. Contexts are a safety feature only when you can see which one is active.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.