Dev Containers and Testcontainers on a Mac

Why the engine matters for tests

A Testcontainers suite starts a real Postgres, Kafka or Redis for a test class, and throws it away afterward. A Dev Container rebuilds and restarts a project's whole toolchain. In both, the time goes into container lifecycle calls: create, start, stop, remove, again and again. Those calls are where Oxcart is fastest.

Oxcart 0.1.2 measured 2026-10-10 with its bundled docker 29.9 client; the other runtimes measured earlier the same day, on the same Mac and harness, with docker 29.4. Apple M5 Max, 8 CPUs and 12 GiB each, one runtime at a time, medians of five samples. Full table: comparisons.

Connect Dev Containers and Testcontainers to Oxcart

1. Install and open Oxcart. Setup creates a Docker context named oxcart. It makes it current only when nothing else is in use, so check with docker context show.
2. Point the docker command at Oxcart. Run docker context use oxcart, or turn on Use Oxcart for the docker command in Settings › Command line tools. Turning it off restores the context you had before.
3. Give test frameworks the socket. For tools that read DOCKER_HOST rather than Docker contexts, export it from the context: export DOCKER_HOST=$(docker context inspect oxcart --format '{{.Endpoints.docker.Host}}').
4. Run your tests. Run your suite as usual. Testcontainers creates, starts and removes its containers through the Docker Engine API.
5. Open the Dev Container. Open the project in its Dev Container, or run devcontainer up --workspace-folder . with the Dev Containers CLI.

Testcontainers

Testcontainers libraries (Java, Go, Node, Python, .NET and the rest) talk to the Docker Engine API directly, not through the docker CLI. Oxcart negotiates API version 1.54 and accepts 1.40 to 1.54, so current Testcontainers releases connect without special settings once they can find the socket.

Finding the socket

Testcontainers looks at DOCKER_HOST first. Oxcart's socket lives in its private state folder, mode 0600, and its path is stored in the oxcart Docker context. Export it once per shell, or set it in your IDE's test configuration:

export DOCKER_HOST=$(docker context inspect oxcart --format '{{.Endpoints.docker.Host}}')
./gradlew test        # or: mvn verify, go test ./..., pytest, npm test

Helper containers and the socket inside containers

Testcontainers starts a small helper container that cleans up after crashed test runs, and some setups run tests inside a container. Both mount the Docker socket. In Oxcart, -v /var/run/docker.sock:/var/run/docker.sock gives a container the same Docker API from inside the Linux side, so helper containers, docker-outside-of-docker, Portainer and Traefik work as they expect. If a tool tries to mount your Mac-side DOCKER_HOST path into a container instead, Testcontainers' standard TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE setting tells it to mount /var/run/docker.sock.

Images built from a Dockerfile

Testcontainers can build an image from a Dockerfile in your test (ImageFromDockerfile and its equivalents). That uses the Engine API's build endpoint, which Oxcart runs on BuildKit, with tar contexts (plain and gzip), build arguments, labels and several tags.

Dev Containers

A Dev Container describes a project's toolchain as a container, and the Dev Containers tooling (the VS Code extension, the devcontainer CLI and the editors that use it) builds and runs it through the docker CLI. With the oxcart context current, that is Oxcart.

Open your project with its toolchain and supporting services together. The Dev Containers CLI starts the workspace alongside services such as Postgres and Redis; your non-root node user can edit the workspace, and the project’s post-create script prepares its dependencies. Teammates get the same environment from the same configuration.

npm install -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

Tips for Dev Containers on Apple silicon

• Architecture: most Dev Container base images publish arm64. For an amd64-only image, Oxcart runs it through Rosetta; see Docker Compose on Apple silicon.
• Dependencies in volumes: put node_modules, package caches and database data in named volumes, and keep the source on the bind-mounted workspace.
• File watching: edits made on the Mac do not produce inotify events inside containers, so a watcher running in the container should use polling.
• Coding agents: an agent running inside a Dev Container keeps its shell in the project's container; an agent on the Mac can inspect the Dev Container's services through Oxcart's MCP server (Docker for AI coding agents).

The Docker context, without surprises

Oxcart creates its oxcart context at setup and makes it current only when that takes nothing from you: when the current context is default and nothing answers at its socket. Otherwise your current context stays. Settings › Command line tools has Use Oxcart for the docker command, which switches to oxcart and remembers the context it replaced; turning it off switches back. Oxcart never creates or replaces /var/run/docker.sock on your Mac, and its API is never on TCP.

Questions

Does Testcontainers work on Apple silicon Macs with Oxcart?

Yes. Testcontainers talks to the Docker Engine API, which Oxcart implements (API versions 1.40 to 1.54), including the build endpoint Testcontainers uses for images built from a Dockerfile. Containers can also mount the Docker socket at /var/run/docker.sock, which Testcontainers' helper containers expect.

How do I set DOCKER_HOST for Testcontainers?

Read it from the oxcart Docker context: docker context inspect oxcart --format '{{.Endpoints.docker.Host}}' prints a unix:// path. Export it as DOCKER_HOST in your shell or your IDE's test run configuration.

Why are my integration tests faster with Oxcart?

Test suites spend much of their time creating, starting, stopping and removing containers. On the same Mac, Oxcart measured 2.5 ms per API create, 18.5 ms per API start, 4.0 ms per API stop, and 77 ms to stop and remove 20 containers: the fastest of the three runtimes we tested at each.

Do VS Code Dev Containers work with Oxcart?

The Dev Containers CLI 0.89.0 built and started a real multi-service configuration on Oxcart, with Postgres and Redis healthy and the workspace writable by the container user. Dev Containers tooling drives the docker CLI, so point the CLI at Oxcart with the oxcart context.

Does docker-outside-of-docker work in a Dev Container?

Yes. Mount /var/run/docker.sock into the container and the docker CLI inside talks to the same engine. Oxcart's private endpoints are refused through that socket, so a container can manage containers but cannot reach Oxcart's own internals.

Will Oxcart replace /var/run/docker.sock on my Mac?

No. Oxcart never creates or replaces /var/run/docker.sock on the Mac. Clients reach it through the oxcart Docker context or the socket path that context names.

Sources and method

• Compatibility: Oxcart's verified integration paths (Engine API build used by docker-py and Testcontainers, Dev Containers CLI 0.89.0, the Docker socket inside containers) and API version range.
• Docker context selection and command-line setup: Oxcart as shipped.
• Speed figures: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPUs and 12 GiB; the other runtimes measured earlier the same day on the same Mac and harness with the docker 29.4 client.