Docker Client Settings and Contexts: Know Where Your Command Goes

When a Docker command reaches an unexpected engine or applies surprising settings, separate two questions:

1. Which client-side files and settings is the Docker CLI using?
2. Which daemon endpoint will receive this command?

DOCKER_CONFIG and --config answer the first question. Docker contexts, host variables, and target-selection flags answer the second. Neither mechanism configures the receiving daemon.

This distinction follows Docker’s client-server architecture. The Docker CLI is a client for interacting with Docker Engine, while Docker Engine includes the dockerd daemon, REST API, and CLI client (Docker glossary).

A responsibility map

This map gives you a useful first cut:

• Unexpected output formatting, credential-store behavior, or plugin settings point toward client configuration.
• Containers or images appearing in the wrong environment point toward context or host selection.
• Unexpected engine behavior after selecting the intended endpoint points toward daemon-side configuration or state.

That is a diagnostic framework derived from Docker’s documented responsibilities, not a tested decision tree.

Client configuration controls what the CLI reads

By default, Docker keeps CLI configuration under ~/.docker, with its main configuration file at ~/.docker/config.json. DOCKER_CONFIG selects another client configuration directory, while the global --config option selects a directory for one invocation (Docker CLI reference).

For example:

docker --config ~/docker-configs/lab image ls

This tells the client where to read its configuration. A directory named lab is just a directory name; it is not a routing instruction and does not inherently select a lab daemon.

Docker’s CLI configuration includes settings for output formatting, registry credential stores, CLI plugins, custom client headers, and proxy variables supplied to containers and builds. These properties do not all have identical scope. In particular, Docker states that the proxy properties in the CLI configuration apply to containers and builds, not as proxy settings for the CLI itself or the daemon (Docker CLI reference).

The configuration directory may contain sensitive registry or proxy authentication information, so inspect its contents before sharing it. Registry credentials managed through docker login should not be confused with a context’s TLS information; Docker’s documentation does not establish that registry login credentials are independently scoped to each context.

Contexts select named Docker environments

A Docker context represents a named environment. Its documented properties include a name and description, endpoint configuration, and TLS information. Contexts allow one client to manage different Docker daemons by switching among stored endpoint configurations (Docker contexts guide).

For example:

docker context use homelab
docker container ls

The first command makes homelab the saved current context. The second targets the endpoints defined by that context unless an environment variable or command-line option overrides it.

Docker documents newly created context metadata under ~/.docker/contexts/, with a meta.json file in a dedicated subdirectory for each context (Docker contexts guide). That page does not specify how choosing an alternate DOCKER_CONFIG affects this context-storage path, so do not assume the two locations move together.

There is also an unrelated terminology collision: a Docker build context is the set of files supplied to a build, whereas a Docker CLI context contains endpoint configuration for connecting to a Docker environment (Docker glossary). Changing one does not mean changing the other.

The saved context is not always the effective target

Docker provides several commands for examining context state:

docker context show
docker context ls
docker context inspect homelab

docker context show prints the current context name. docker context ls marks the active context with an asterisk, while docker context inspect displays details for one or more contexts (docker context reference).

That active context is a default, not an unconditional routing rule. Docker documents several ways to override it.

DOCKER_CONTEXT selects a context through the environment and overrides the context saved by docker context use:

export DOCKER_CONTEXT=homelab
docker container ls

A command can also select a context directly:

docker --context homelab container ls

Docker documents --context as overriding DOCKER_HOST and the default selected with docker context use (Docker CLI reference).

Alternatively, DOCKER_HOST specifies a daemon socket directly, and -H or --host can supply a socket for an invocation:

DOCKER_HOST=unix:///path/to/docker.sock docker container ls

Docker’s linked pages do not provide a complete precedence order for every simultaneous combination of --host, --context, DOCKER_HOST, and DOCKER_CONTEXT. When several are set, remove the ambiguity instead of relying on an assumed total ordering.

Checklist: identify the intended target

Work from invocation-specific controls toward saved defaults.

1. Read the exact command. Look for --context, -c, --host, -H, or --config.

2. Inspect relevant environment variables.

bash
printenv DOCKER_CONTEXT
printenv DOCKER_HOST
printenv DOCKER_CONFIG

DOCKER_CONTEXT and DOCKER_HOST affect target selection. DOCKER_CONFIG identifies client-side files.

3. Check the saved context.

bash
docker context show
docker context ls

The asterisk in docker context ls may not represent the effective target when an override applies.

4. Inspect the relevant context.

bash
docker context inspect homelab

Compare its stored endpoint with the endpoint you intended to use.

5. Make the next invocation explicit.

bash
docker --context homelab container ls

This process identifies the target implied by the documented inputs for a new command. It does not test endpoint reachability, authenticate which daemon responds, or reconstruct the destination of a command that already completed. No hands-on test was performed for this explanation.

The shortest useful diagnostic question is: Is the problem what this client reads, where this command goes, or how the receiving daemon behaves?

Sources and further reading

• https://docs.docker.com/reference/glossary
• https://docs.docker.com/reference/cli/docker
• https://docs.docker.com/engine/manage-resources/contexts
• https://docs.docker.com/reference/cli/docker/context