Update a Docker Context Without Losing Its Endpoint

You will change an existing Docker context's description or Docker endpoint, then confirm the stored values before using it. Allow about ten minutes for a description-only change, or longer if you need to check TLS material with the context owner. The examples use Docker CE CLI 29.8.1, installed from the docker-ce-cli package on this machine.

1. Find the context you intend to change

A context is a named set of client connection settings. Updating one changes the saved configuration for every later command that selects it. It does not create a context and it does not switch the current context. Start by listing the names and checking which one has the asterisk:

$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
production                                            tcp://docker.example.test:2376

Replace production below with the exact name from your own output. Do not guess a context name, especially before changing a remote endpoint. Check its current configuration as a checkpoint:

$ docker context inspect production
[
    {
        "Name": "production",
        "Endpoints": {
            "docker": {
                "Host": "tcp://docker.example.test:2376",
                "SkipTLSVerify": false
            }
        }
    }
]

The full inspection also shows metadata and paths to stored context material. Save the relevant output somewhere secure if you may need to undo the change. Certificate paths and endpoint names can be security-sensitive.

2. Change only the description

For a label change, use --description and the context name. This does not alter where Docker connects:

$ docker context update production \
    --description "Production Docker host"
production
Successfully updated context "production"

Verify the metadata and endpoint separately:

$ docker context inspect production \
    --format '{{.Name}}: {{.Metadata.Description}} - {{.Endpoints.docker.Host}}'
production: Production Docker host - tcp://docker.example.test:2376

If the description contains spaces, keep the quotes. An empty description is accepted by the CLI syntax, but it removes useful identification, so use a deliberate label rather than relying on the command's default.

3. Change the Docker endpoint deliberately

The --docker option takes comma-separated key-value settings. The installed manpage documents from, host, ca, cert, key and skip-tls-verify. A local socket change looks like this:

$ docker context update production \
    --docker "host=unix:///var/run/docker.sock"
production
Successfully updated context "production"

For a TLS endpoint, provide the complete set of values you intend to use:

$ docker context update production \
    --docker "host=tcp://docker.example.test:2376,ca=/path/to/ca.pem,cert=/path/to/client-cert.pem,key=/path/to/client-key.pem"
production
Successfully updated context "production"

Use real paths, not the placeholders. The tilde in a path is shown in Docker's example, but quoting and shell expansion can be easy to misread in scripts; an absolute path is clearer. Docker stores endpoint settings in the context. It does not make a remote daemon reachable, repair certificates, or grant your user access to a socket.

4. Treat TLS bypass as an emergency setting

skip-tls-verify=true disables certificate validation for that context. That can expose credentials and Docker control traffic to an impostor endpoint. Do not use it as a routine fix for an expired, incorrect or untrusted certificate. If an incident procedure explicitly requires it, record the reason and restore validation immediately afterwards:

$ docker context update production \
    --docker "host=tcp://docker.example.test:2376,skip-tls-verify=true"
production
Successfully updated context "production"

$ docker context inspect production \
    --format '{{json .Endpoints.docker}}'
{"Host":"tcp://docker.example.test:2376","SkipTLSVerify":true}

This is a security-sensitive change, not a harmless connectivity option. Prefer fixing the CA and client certificate paths, then set skip-tls-verify=false or replace the endpoint settings with the verified TLS values.

5. Check which context your next command will use

docker context update does not select the context. The current selection can still be default, while DOCKER_CONTEXT or the global --context option can override it for a command. Check before running a command that creates, removes or inspects containers:

$ docker context show
default
$ docker --context production info

The info command may produce a long response and requires a reachable daemon. If you only need to check the saved endpoint without connecting, use docker context inspect as above. Do not use sudo merely because you changed a context. Use elevated privileges only when the selected endpoint or its socket permissions genuinely require them, and remember that sudo docker may use a different Docker configuration.

6. Undo a mistaken update

There is no separate undo flag. Restore the values you recorded before the update. For example, this puts a context back on a local socket and re-enables certificate validation:

$ docker context update production \
    --description "Original production context" \
    --docker "host=tcp://docker.example.test:2376,ca=/path/to/old-ca.pem,cert=/path/to/old-cert.pem,key=/path/to/old-key.pem,skip-tls-verify=false"
production
Successfully updated context "production"

$ docker context inspect production \
    --format '{{json .Endpoints.docker}}'
{"Host":"tcp://docker.example.test:2376","SkipTLSVerify":false}

If you did not record the old values, inspect shell history, an approved configuration backup or a context export made before the change. Do not copy private keys into tickets or paste them into chat. If the update pointed a production context at the wrong daemon, stop using that context, restore the verified endpoint, and ask the service owner to check for commands sent during the interval.

7. Diagnose the usual failures

An error saying that the context does not exist means the name is wrong or the command is reading a different Docker configuration. Compare docker context ls with docker context show, and check whether DOCKER_CONFIG is set. A successful update followed by a failed docker info usually means the saved endpoint, network route, daemon or credentials are wrong; it does not mean the update syntax failed.

If a setting contains a comma, shell quoting alone is not enough to make it one Docker key-value value because Docker uses commas to separate the endpoint fields. Keep paths and values simple, and verify the resulting JSON after every endpoint update. If only the description changed, inspect the endpoint too: the safest checkpoint proves both the field you meant to change and the connection target you meant to preserve.