The Engine API — what the CLI is really doing · Docker & Containers

docker ps is an HTTP GET. The CLI holds no state, performs no container logic, and knows nothing the daemon does not tell it. It opens /var/run/docker.sock, issues a request, and formats the JSON that comes back.

Once you have seen that, three things stop being mysterious: why a new CLI works against an old daemon, why docker attach behaves unlike every other subcommand, and why an engine upgrade breaks a monitoring integration nobody touched.

The socket is an HTTP server

Read-only / Safe/_ping— The cheapest possible daemon health check. Everything a client needs to negotiate is in the response headers.

$ curl -s -i --unix-socket /var/run/docker.sock http://localhost/_ping

HTTP/1.1 200 OK
Api-Version: 1.55
Builder-Version: 2
Cache-Control: no-cache, no-store, must-revalidate
Docker-Experimental: false
Ostype: linux
Pragma: no-cache
Server: Docker/29.7.1 (linux)
Swarm: inactive
Date: Tue, 11 Aug 2026 15:31:20 GMT
Content-Length: 2
Content-Type: text/plain; charset=utf-8

/_ping is the endpoint the CLI hits first, every time, and the whole point of it is those headers. Api-Version is what the daemon speaks. Swarm and Ostype tell the client which subcommands make sense.

The rest of the API follows the same pattern:

Read-only / Safethe CLI, by hand— Each of these is what the corresponding docker subcommand issues. jq is optional but makes the output readable.

SOCK=/var/run/docker.sock

# docker version
curl -s --unix-socket "$SOCK" http://localhost/version

# docker ps
curl -s --unix-socket "$SOCK" http://localhost/containers/json

# docker ps -a
curl -s --unix-socket "$SOCK" 'http://localhost/containers/json?all=true'

# docker inspect
curl -s --unix-socket "$SOCK" http://localhost/containers/grafana/json

# docker info
curl -s --unix-socket "$SOCK" http://localhost/info

Versioned paths and negotiation

Every endpoint also exists under a version prefix:

curl -s --unix-socket /var/run/docker.sock \
  'http://localhost/v1.44/containers/json?limit=1'

The daemon serves the request according to the semantics of that API version — field names, defaults and response shapes as they were at 1.44 — even though it is a 1.55 daemon.

That is what makes a newer CLI work against an older daemon. On startup the CLI pings, reads Api-Version, and issues subsequent requests at the lower of its own maximum and the daemon’s. This is version negotiation, and it happens silently.

Read-only / Safepinning the client— DOCKER_API_VERSION forces a version and disables negotiation. The daemon still reports its own.

$ docker version --format '{{.Client.APIVersion}} / {{.Server.APIVersion}}'
DOCKER_API_VERSION=1.44 docker version --format '{{.Client.APIVersion}} / {{.Server.APIVersion}}'

1.55 / 1.55
1.44 / 1.55

Pinning is occasionally the right answer — reproducing a bug, or working around a response-shape change — and it is a footgun the rest of the time, because it also disables the automatic downgrade. Set it in a script and that script will fail against a daemon older than the pin, with an error about the version rather than about the problem.

The compatibility floor

Negotiation only works downward to a point. Every daemon publishes a minimum:

Read-only / Safebelow the floor— A request under MinAPIVersion is rejected with HTTP 400 and that message.

$ curl -s --unix-socket /var/run/docker.sock http://localhost/version | \
python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["Version"], d["ApiVersion"], d["MinAPIVersion"])'
curl -s --unix-socket /var/run/docker.sock http://localhost/v1.20/containers/json

29.7.1 1.55 1.40
client version 1.20 is too old. Minimum supported API version is 1.40, please upgrade your client to a newer version

MinAPIVersion moves when the engine drops support for old clients, and that is where upgrades bite.

The integration that breaks is the one nobody remembers writing

The Docker CLI negotiates, so operators upgrade an engine and see nothing wrong. What does not negotiate is everything else that talks to the socket, and every host has some:

A monitoring agent using a pinned SDK version.
A CI runner with a vendored Docker client library.
A Compose plugin from a distribution package, several releases old.
A backup script that hardcodes /v1.24/ in a curl call because that is what the example on the internet used in 2017.

Each of these starts returning HTTP 400 the moment MinAPIVersion passes its pin. The failure is a plain-text error inside somebody else’s log file, and the correlation with last week’s engine upgrade takes a while to make.

Before an engine major upgrade, inventory what talks to the socket:

sudo ss -xp | grep docker.sock
grep -rn 'docker.sock\|DOCKER_API_VERSION\|/v1\.[0-9]' \
  /etc/cron.d /usr/local/bin /opt 2>/dev/null

and check the release notes for a MinAPIVersion change.

Streaming endpoints

Most endpoints return a JSON document and close. A few hold the connection open and stream, which is why they behave differently from everything else:

Endpoint	CLI	Behaviour
`/events`	`docker events`	Newline-delimited JSON, indefinitely
`/containers/{id}/stats`	`docker stats`	One JSON object per sample
`/containers/{id}/logs?follow=true`	`docker logs -f`	Multiplexed stdout/stderr frames
`/containers/{id}/attach`	`docker attach`	HTTP connection upgrade to a raw bidirectional stream

Read-only / Saferaw event stream— curl -sN disables buffering. Each line is one event object.

$ timeout 2 curl -sN --unix-socket /var/run/docker.sock \
'http://localhost/events?since=0&until=0' | head -c 200

{"Type":"container","Action":"exec_start: /bin/sh -c wget --quiet --spider http://127.0.0.1:9090/-/healthy || exit 1","Actor":{"ID":"b8b6efd9481d82e9a0449ee1a1e4862b7fbc2fea8a62f0f688591590704c9d81","Attributes":{"com.docker.compose.config-hash":"043

What if you need this over the network rather than the socket?

The API is the same over TCP, and exposing it is the single most dangerous configuration change available on a Docker host: an unauthenticated TCP port with root-equivalent control of the machine.

If you genuinely need remote access, do not open tcp:// at all. Use an SSH context, which tunnels the socket over an authenticated channel you already operate:

docker context create prod --docker 'host=ssh://deploy@host01.example.com'
docker context use prod
docker context ls

The client speaks the same API to the same socket; SSH provides the authentication and encryption. If TCP is unavoidable, mutual TLS with client certificate verification is the minimum, and it is strictly more moving parts than the SSH route for less safety.

Sanity check

Why this matters

Treating the CLI as the product hides two things that cost real time.

The first is diagnostic reach. When a subcommand gives you a formatted summary and you need the field it dropped, the raw endpoint has it — no flag hunting, no --format template guessing, just the JSON the daemon actually returned. The same applies when you are writing an integration: the API is documented, versioned and stable in ways CLI output formatting is not.

The second is upgrade risk. Version negotiation makes the CLI resilient and makes everything else on the host silently fragile. The clients that break on an engine upgrade are the ones nobody thinks of as clients — an agent, a plugin, a cron script — and they break with an HTTP status code rather than an error anyone will connect to the upgrade. Knowing that MinAPIVersion exists, and checking it before the change window, is the whole mitigation.