dockerode

dockerode is a Node.js module that wraps the Docker Engine Remote API in a set of first-class JavaScript entities — containers, images, networks, volumes, execs, services, and more — instead of a pile of loose static functions. It preserves Node streams end-to-end (including optional demultiplexing of combined stdout/stderr), and offers both callback- and promise-based interfaces so it fits either coding style.

Beyond low-level API coverage, dockerode ships convenience helpers like docker.run() (a docker run equivalent with automatic container lifecycle handling) and followProgress() for tracking long-running operations such as image builds and pulls. It supports connecting over a Unix socket, TCP, or TLS-secured remote hosts, making it equally usable for local development tooling and remote Docker/Swarm orchestration from Node.js.

What You Get

• Entity-based wrappers for containers, images, networks, volumes, execs, services, tasks, nodes, plugins, secrets, and configs instead of raw endpoint calls
• Unbroken Node.js streams for attach/logs/build output, with an optional demuxStream() helper to split combined stdout/stderr
• Both callback and Promise-based method signatures across the entire API surface, including support for swapping in an alternate Promise library
• A docker.run() convenience method that replicates docker run semantics — create, start, and optionally auto-remove a container in one call
• followProgress() for tracking multi-step async operations like image builds and pulls to completion
• Connection options for Unix sockets, plain TCP, and TLS-secured remote/Swarm hosts

Common Use Cases

• Building CI/CD tooling or internal PaaS platforms that programmatically create, start, and tear down containers
• Writing developer-facing CLIs or dashboards that need live container logs and stats via streams
• Automating Docker image builds and registry pulls/pushes as part of a Node.js build pipeline
• Orchestrating multi-container test environments (spin up, exec into, and clean up containers) from a test suite
• Managing Docker Swarm services, nodes, and secrets from Node.js operational scripts

Under The Hood

Architecture dockerode’s core is lib/docker.js, a Docker constructor that owns a single docker-modem instance (this.modem) responsible for the actual HTTP/socket transport, TLS negotiation, and request serialization; every entity module (container.js, image.js, network.js, volume.js, service.js, task.js, node.js, plugin.js, secret.js, config.js, exec.js) is a thin wrapper that stores an id and delegates all I/O to modem.dial(), so the library’s real behavior — connection handling, chunked/streamed responses, and promise vs. callback branching — lives in the separate docker-modem dependency rather than in dockerode itself. Tech Stack it’s plain CommonJS JavaScript (99.9% of the repo) with a deliberately small dependency set — docker-modem for transport, tar-fs + @balena/dockerignore for build-context tarring, @grpc/grpc-js and protobufjs for the newer buildkit/session gRPC paths (lib/buildkit.js, lib/session.js, lib/proto/), and no TypeScript, transpilation, or bundler step — main in package.json points straight at ./lib/docker.js. Code Quality the test/ directory holds ~3,000 lines across dedicated files per entity (container.js, image.js, networks.js, swarm.js, buildkit_test.js, etc.) run through Mocha/Chai, with fixtures and a spec_helper.js for shared setup, indicating deliberate per-feature coverage; the production code favors small, single-purpose prototype methods with consistent JSDoc blocks over each public method, though it still uses older callback-first patterns (processArgs, manual EventEmitter wiring) rather than modern async/await internally. API Design the object-oriented split (docker.getContainer(id) returns a lightweight handle before any network call, methods like .inspect()/.start()/.remove() act on it) keeps call sites close to the Docker CLI’s own mental model, and the dual callback/Promise support on every method (return a Promise only when no callback is passed) minimizes boilerplate for both legacy callback code and modern async/await consumers, at the cost of needing to remember which calling convention was used for a given snippet found in older documentation or examples.