🐳 n8n-nodes-docker-api

Control Docker from your n8n workflows — 58 operations plus an event trigger,
with output you can feed straight into an IF node.

---

✨ Why this node

No dependencies. Talks to the Docker Engine API directly over a socket, TCP
or TLS. If you already run Portainer, it can go through that too — but nothing
extra is required.

Output you can actually use. Docker's raw responses are verbose, deeply
nested, and inconsistent between endpoints. Everything here is normalized to a
flat, stable shape, and the same container looks the same whichever operation
returned it.

// List Containers — one item
{
  "id": "e324df4bd041772cc01172d392a4c2faa87d63614b8c0d0ab859919cb9a84432",
  "shortId": "e324df4bd041",
  "name": "api-gateway",
  "image": "nginx:alpine",
  "status": "running",
  "health": "healthy",
  "createdAt": "2026-07-31T13:45:48.000Z",
  "ports": [{ "containerPort": 80, "hostPort": 8080, "protocol": "tcp" }],
  "labels": { "com.example.tier": "edge" }
}

Safe by default. Credentials carry an access mode, enforced at run time — not
just hidden in the UI. Every destructive operation offers a dry run, and every
prune shows you exactly what it would remove first.

It tells you when it doesn't know. An empty result always says whether it
means nothing found or not looked up. Operations that cannot return complete
information say so in the output rather than returning a confident half-answer.

---

📦 Install

Community Nodes (recommended)

Settings → Community Nodes → Install → n8n-nodes-docker-api

Manual

npm install n8n-nodes-docker-api

Requires a self-hosted n8n with access to a Docker daemon.

---

🚀 Quick start

1. Add a Docker API credential and pick a connection mode
2. Press Test Connection — it reports the daemon version on success
3. Add the Docker API node, choose a resource and operation

---

🔌 Connecting

Mode	Use when
Unix Socket / Named Pipe	Docker runs on the same machine as n8n
TCP	Remote daemon on a trusted private network
TLS	Remote daemon, encrypted with client certificates
Portainer	You already run Portainer and want to go through it

The socket path defaults correctly for the host n8n is running on —
/var/run/docker.sock on Linux and macOS, //./pipe/docker_engine on Windows.

Access modes

Set on the credential and enforced at run time:

• Read Only — listing, inspection, logs, stats. Write operations are refused
  with a clear message.
• Full Control — everything.

Unrecognised operations are denied under Read Only rather than allowed, so a
future addition can never quietly widen what a read-only credential can do.

---

📋 Operations

Containers (24)

Read	List · Inspect · Get Logs · List Processes · Get Filesystem Changes · Get Stats
Lifecycle	Create · Start · Stop · Restart · Kill · Pause · Unpause · Rename · Remove · Prune
Files & state	Export · Copy From · Copy To · Get Path Info · Update (limits, restart policy)
Beyond the API	Run (Ephemeral) · Execute Command · Wait For State

Run Container (Ephemeral) creates, runs, captures output and removes — in one
step. The container is cleaned up on every path, including timeout, so a workflow
that fails midway never leaves one behind.

Execute Command returns { stdout, stderr, exitCode } from a single
operation, with the two streams kept separate.

Create Container covers what a real deployment needs, not just the basics:
health check, CPU and memory limits, capabilities, devices, extra hosts, DNS,
shared memory size, tmpfs mounts, an init process, restart policy and network
mode — alongside ports, volumes, environment and labels.

Wait For State blocks until a container is running, healthy or exited.
Waiting on healthy is the piece every deploy-then-verify workflow needs, and
Docker has no endpoint for it.

Get Logs returns structured lines with their stream of origin:

{ "logs": [ { "message": "listening on :8080", "stream": "stdout" },
            { "message": "upstream timeout",   "stream": "stderr" } ],
  "lineCount": 2, "tty": false }

Get Stats returns numbers people actually want — cpuPercent,
memoryUsageMB, memoryPercent, networkRxMB — rather than Docker's raw
cumulative counters.

Copy From / To Container moves files through n8n's binary data system, so
they can be written to disk, uploaded, or attached like any other file.

Images (15)

List · Inspect · Get History · Search · Pull · Push · Tag · Remove · Prune ·
Build · Create From Container · Save · Load · Prune Build Cache ·
Get Registry Info

Build takes a Dockerfile as text for the common case, or a tar context when the
build needs to COPY local files. Create From Container snapshots a running
container as an image. Save and Load move images as tar archives through
n8n binary data, for backups or air-gapped transfer. Prune Build Cache
reclaims the builder cache, which image pruning never touches and which is often
the largest recoverable space on a build machine.

Get Registry Info reads an image’s digest and platform list straight from the
registry without pulling it — a few kilobytes instead of the whole image. Compare
the digest against what is currently running to tell whether a rebuild is
actually needed, or check a tag exists for your architecture before a deploy
commits to it.

Pull and Push wait for completion and return a summary — layers, digest, status,
duration — instead of a progress firehose or a stream that never ends.

Networks (7)

List · Inspect · Create · Connect Container · Disconnect Container · Remove · Prune

Volumes (5)

List · Inspect · Create · Remove · Prune

System (6)

Get Info · Get Version · Ping · Get Disk Usage · Get Events · Check Registry Credentials

Custom API Call

An escape hatch to any Docker Engine endpoint, for anything not covered above or
a newer API than this release knows about. The response comes back exactly as
Docker sent it and is marked normalized: false — the one operation that
deliberately does not promise a stable shape.

---

⚡ Docker Trigger

Start a workflow when something happens in Docker.

Watches containers, images, networks, volumes and the daemon. Filter by event
type, action, container, image or label — filters are applied by Docker, so only
matching events are sent.

It catches up. Docker's event stream is live-only: connect, and you get what
happens next and nothing earlier. If n8n restarts, a naive listener silently
loses everything that happened in between — which is exactly when something worth
knowing about tends to occur. This trigger remembers where it got to and replays
from there, without ever delivering the same event twice.

It reconnects. Event streams die for ordinary reasons — daemon restarts,
socket hiccups, a laptop sleeping. It reconnects with backoff rather than quietly
stopping.

---

🔥 Real use cases

♻️ Self-healing containers

A container dies at 3am. Nobody is awake. It comes back by itself.

Docker Trigger (container · die)  →  IF (name = api-gateway)  →  Docker: Start Container

The trigger catches up on anything that happened while n8n itself was
restarting, so a crash during a deploy window is not silently lost.

🚨 Alert before your users notice

Health status changes reach you before the support ticket does.

Docker Trigger (container · health_status)  →  IF (health = unhealthy)  →  Slack

🚢 Deploy and verify

Pull, replace, and wait for the new container to report healthy — not merely
running, which is the difference between a deploy that worked and one that
only looks like it did.

Docker: Get Registry Info  →  IF (digest changed)  →  Docker: Pull Image
   →  Docker: Remove Container  →  Docker: Create Container
   →  Docker: Wait For State (healthy)  →  Slack

Get Registry Info checks for a new version without downloading the image, so the
schedule costs kilobytes on every day that nothing has changed.

🧪 Run a job in a disposable container

Schedule  →  Docker: Run Container (Ephemeral)  →  IF (exitCode = 0)  →  …

Nothing is left behind — the container is removed on every path, including
timeout, so a workflow that fails midway never accumulates containers.

📊 Nightly disk report

Schedule  →  Docker: Get Disk Usage  →  Docker: Prune Images (Dry Run)  →  Email

The dry run reports exactly what would be reclaimed, so the report is
informative without being destructive.

---

🩹 When the daemon goes away

Docker restarts. Sockets briefly lose their permissions. A proxy hiccups. These
fail a workflow step that would have succeeded a second later.

Every request retries automatically on failures that never reached the daemon —
ECONNREFUSED, a missing or unreadable socket, an unreachable host, or a
502/503/504 from a proxy in front of Docker. Three attempts with
exponential backoff by default, configurable under Connection Retry.

Anything Docker actually answered is never retried. A missing container, a
name conflict, a refused registry login — the daemon was reachable and gave a
considered reply, so retrying would only bury a configuration problem under a
delay.

A write is never repeated once it may have been applied. If the connection
breaks after the request was sent, the daemon may already have created that
container. Reads are retried; writes are not, and the error says the outcome is
unknown rather than implying nothing happened.

Retries are per request, so an item that already succeeded is never re-run. This
matters more than it sounds: n8n's built-in Retry On Fail re-executes the
whole node, so a batch of fifty containers where the last one fails would create
the first forty-nine again. Leave it off for this node.

---

🔒 Security

Access to the Docker daemon is equivalent to root on the host. That is true of
any tool that talks to Docker, and worth stating plainly.

• Use Read Only credentials unless a workflow genuinely needs to change things
• Prefer TLS over plain TCP for anything crossing a network
• Consider a socket proxy such as tecnativa/docker-socket-proxy to restrict
  which endpoints are reachable at all
• Never expose the Docker daemon on a public interface

The credential UI carries this warning too, and Read Only is the default.

---

🗺️ Scope

This node covers containers, images, networks, volumes and system operations —
the surface that automation workflows actually use.

Swarm mode (services, nodes, tasks, secrets, configs) and plugin
management are deliberately out of scope. Teams running Swarm manage it with
Swarm-native tooling rather than from workflow steps, and supporting it well
would mean a large surface serving very few n8n users. Anything genuinely needed
remains reachable through Custom API Call.

---

⭐ Contributing

Issues and pull requests are welcome — particularly bug reports with a
reproducible workflow. See DEVELOPMENT.md for the local
setup and test harness.

📄 License

MIT