Manage Isolated Docker Endpoints with Contexts

You will finish with a named Docker context that can be inspected, selected for ordinary Docker commands, exported, and removed without confusing it with the daemon itself. The examples use Docker CLI 29.8.1 from the installed docker-ce-cli package. Allow about fifteen minutes. You need a shell and a Docker endpoint you are authorised to use. Reading and changing client contexts is normally unprivileged; access to the daemon may still require membership of the docker group or another host-specific permission.

A context stores endpoint information for the client. It does not create a daemon, grant access, or make an insecure remote endpoint safe. Treat a remote Docker socket as highly privileged: anyone who can control a Docker daemon can usually control the host running it.

1. Check the installed command

Start with the command group and version. These are read-only checks:

$ docker context
Manage contexts
$ docker version --format '{{.Client.Version}}'
29.8.1
$ dpkg-query -W docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble

The top-level command lists the available operations. The installed command also supports create, ls, inspect, use, update, rm, export and import. Checkpoint: if docker context is not recognised, stop here and use a Docker CLI that provides contexts.

2. Record the current context

Before selecting anything, record what is active and where it points:

$ docker context show
default
$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

The asterisk marks the active context. The default context follows the client's normal local configuration, often the Unix socket shown above. Your endpoint and error column may differ. Save this information before making changes so that you have an exact value to restore later.

3. Create a context for a local or remote endpoint

Give the context a specific name and description. This local example points at the usual Unix socket and does not contact a remote host:

$ docker context create lab-docker --description 'Lab Docker daemon' \
    --docker 'host=unix:///var/run/docker.sock'
lab-docker
Successfully created context "lab-docker"

The --docker value sets the Docker endpoint. For a TLS-protected remote daemon, the manpage also accepts ca, cert and key values, for example:

$ docker context create REMOTE_NAME \
    --description 'Authorised remote Docker daemon' \
    --docker 'host=tcp://REMOTE_HOST:2376,ca=/path/to/ca.pem,cert=/path/to/client-cert.pem,key=/path/to/client-key.pem'

Replace every uppercase placeholder, and check file permissions before using private key material. Do not add skip-tls-verify merely to get a connection working. Skipping certificate verification removes an important identity check and needs a documented, temporary reason.

Checkpoint: inspect the result before selecting it:

$ docker context inspect lab-docker
[
    {
        "Name": "lab-docker",
        "Metadata": {
            "Description": "Lab Docker daemon"
        },
        "Endpoints": {
            "docker": {
                "Host": "unix:///var/run/docker.sock",
                "SkipTLSVerify": false
            }
        }
    }
]

Storage paths and some fields vary by installation. The important checks are the context name, endpoint host, and TLS verification setting.

4. Select it, then verify before running Docker commands

Selecting a context changes which endpoint subsequent Docker commands target. This is a client setting, but it can make a command affect a different host:

$ docker context use lab-docker
Current context is now "lab-docker"
lab-docker
$ docker context show
lab-docker
$ docker context ls
NAME          DESCRIPTION          DOCKER ENDPOINT               ERROR
default       ...                  unix:///var/run/docker.sock
lab-docker *  Lab Docker daemon    unix:///var/run/docker.sock

The exact table spacing and default description vary. Verify the asterisk and inspect the selected context before commands that create, remove, or publish containers, images, volumes or networks. For a one-off override, the global option avoids changing the saved selection:

$ docker --context lab-docker info

If DOCKER_CONTEXT is set in the shell environment, it can override the saved selection. Check it when docker context show and an observed command appear to disagree:

$ printenv DOCKER_CONTEXT

5. Update metadata or endpoint details

Use update when an existing context needs a new description or Docker endpoint:

$ docker context update lab-docker --description 'Primary lab daemon'
lab-docker
Successfully updated context "lab-docker"
$ docker context inspect lab-docker

Changing a host, certificate, or key changes where later commands go. It does not migrate containers or test the new daemon for you. Run the inspect check again, then use a harmless read-only command such as docker --context lab-docker version if you are authorised to contact the endpoint. A connection failure usually means the host, network path, certificate chain, credentials, or daemon access policy needs checking; do not weaken TLS verification as a first response.

6. Export and import a context carefully

Export is useful for moving client configuration between machines:

$ docker context export lab-docker /path/to/lab-docker.dockercontext
Written file "/path/to/lab-docker.dockercontext"
$ ls -l /path/to/lab-docker.dockercontext

Protect the export file. A context can contain endpoint details and TLS material. Move it only through a trusted channel and remove it using your normal secure-file procedure when it is no longer needed. Import it under a new name for a non-destructive check:

$ docker context import lab-docker-copy /path/to/lab-docker.dockercontext
lab-docker-copy
Successfully imported context "lab-docker-copy"
$ docker context inspect lab-docker-copy

Import creates a context; it does not make it active. Compare the imported endpoint with the source before using it, and do not overwrite a name that is already meaningful on the destination host.

7. Remove test contexts and restore the original

Removal deletes the client-side context definition. It does not delete containers or stop the daemon, but it can make saved workflows fail if they refer to that name:

$ docker context use default
Current context is now "default"
$ docker context rm lab-docker-copy
lab-docker-copy

If a context is active, the command refuses ordinary removal. The -f option forces removal of an in-use context, so use it only when you have confirmed the name and no shell, script, or operator still needs it:

$ docker context rm -f lab-docker

Do not force removal as a shortcut for uncertainty. If you removed the wrong context, recreate it from a verified export or repeat docker context create with the exact endpoint and TLS files. There is no general undo command for a removed context.