Socktainer 🚢
[!NOTE]
socktainer maintains to be compatible with Docker Engine API v1.51.
> Progress is tracked in #14 and #90.- Quick Start ⚡ - Launch socktainer 🏁 - Using Docker CLI 🐳 - Key Features ✨ - Requirements 📋 - Installation 🛠️ - Homebrew - Stable Release - Pre Release - GitHub Releases - Usage 🚀 - Volume sync mode - VM memory - DNS upstream - Volume compatibility — Postgres - Building from Source 🏗️ - Prerequisites - Build & Run - Testing ✅ - Contributing 🤝 - Workflow - Developer Notes 🧑💻 - Security & Limitations ⚠️ - Community 💬 - License 📄 - Acknowledgements 🙏
Socktainer is a CLI/daemon that exposes a Docker-compatible REST API on top of Apple's containerization libraries 🍏📦.
It allows common Docker clients (like the Docker CLI) to interact with local containers on macOS using the Docker API surface 🐳💻.
📖 Documentation and website: socktainer.github.io
Podman Desktop Apple Container extension uses socktainer to visualize Apple containers/images in Podman Desktop.
Quick Start ⚡
Get started with socktainer CLI in just a few commands:
Launch socktainer 🏁
./socktainer
[ INFO ] Docker context 'socktainer' ready — run: docker context use socktainer
[ NOTICE ] DNS server listening on port 2054
[ NOTICE ] Server started on http+unix: $HOME/.socktainer/container.sock
...
If Apple Container's own service isn't already running, socktainer starts it
automatically first (like colima does for Docker) — no separate container
system start step needed — then continues with the rest of startup above:
Launching container-apiserver...
[ INFO ] Apple Container service not running — attempting to start it...
[ INFO ] Apple Container service started
[ INFO ] Docker context 'socktainer' ready — run: docker context use socktainer
...
Opt out of automatic Apple Container startup
Pass --no-auto-start to skip this — useful in CI or when managing Apple
Container's lifecycle yourself. If the service still isn't running, the normal
compatibility check (unless that's also disabled) catches it and aborts with a
clear message rather than starting socktainer against a dead backend:
socktainer --no-auto-start
Using Docker CLI 🐳
Socktainer automatically registers a socktainer Docker context on startup.
Activate it once:
docker context use socktainer
Then use Docker normally — no DOCKER_HOST needed:
docker ps # List running containers
docker ps -a # List all containers
docker images # List available images
Switch back to another runtime at any time:
docker context use colima # or "default", etc.
Opt out of automatic context creation
Pass --no-docker-context to skip writing the context file on startup — useful
in CI or when managing Docker contexts manually:
socktainer --no-docker-context
Note: this flag skips creating the context but does not remove one that was
already created. To remove it: docker context rm socktainer.
Alternative: set DOCKER_HOST manually
export DOCKER_HOST=unix://$HOME/.socktainer/container.sock
docker ps
docker images
Or inline without exporting:
DOCKER_HOST=unix://$HOME/.socktainer/container.sock docker ps
DOCKER_HOST=unix://$HOME/.socktainer/container.sock docker images
Key Features ✨
- Built on Apple’s Container Framework 🍏
- Provides Docker REST API compatibility 🔄 (partial)
- Listens on a Unix domain socket
$HOME/.socktainer/container.sockand auto-registers asocktainerDocker context - Supports container lifecycle operations: inspect, stop, remove 🛠️
- Supports image listing, pulling, deletion, logs, health checks, container stats. Exec without interactive mode 📄
docker statsreports memory against the Apple Container VM limit (configurable via--memory, default 1 GiB per container), not the host RAM- Broadcasts container events for client liveness monitoring 📡
Requirements 📋
- macOS 26 (Tahoe) on Apple Silicon (arm64) Apple’s container APIs only work on arm64 Macs 🍏💻
- Apple Container 1.7.1
Installation 🛠️
Homebrew
socktainer is included in Homebrew Formulae:
brew install socktainer
If you want to install the latest head version of socktainer:
brew install socktainer --HEAD
[!NOTE]
Formerly we have provided our own Homebrew tap. You may want to integrate it with the Homebrew official, and you can run the following command:
>> brew untap socktainer/tap
GitHub Releases
Download from socktainer releases page the zip or binary. Ensure the binary has execute permissions (+x) before running it.
Usage 🚀
Refer to Quick Start above for immediate usage examples.
Volume sync mode
Named volumes default to nosync — guest fsync() calls are not flushed to the
host disk on demand, matching Colima's behavior and giving ~1.5× speedup for
write-heavy workloads (postgres WAL, Kafka, Redis AOF).
Tradeoff: data written to a volume since the last OS page-cache flush could be
lost if the host (Mac) crashes or loses power. In a dev environment this is
acceptable; data is safe across normal docker stop / host restarts.
Override globally — apply the same mode to all named volumes (bind mounts and anonymous volumes are not affected):
socktainer --volume-sync=fsync # honor guest fsyncs (durable)
socktainer --volume-sync=full # fully synchronous writes (slowest)
socktainer --volume-sync=nosync # default
Override per volume — docker volume create -o sync= persists the
choice for that volume regardless of the global flag:
docker volume create -o sync=fsync my-pgdata
docker run -v my-pgdata:/var/lib/postgresql/data postgres
Or using Docker Compose with driver_opts:
services:
postgres:
image: postgres:latest
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
driver: local
driver_opts:
sync: fsync
Valid modes: nosync · fsync · full
VM memory
Each container runs in its own Apple Container VM with a fixed memory allocation.
Socktainer honors Docker's --memory flag and mem_limit: / deploy.resources.limits.memory: in Compose files.
docker run --memory 2g postgres # 2 GiB VM
docker run --memory 512m redis # 512 MiB VM
docker run postgres # 1 GiB VM (Apple Container default)
Note: Apple Container allocates VM RAM at creation time — this is not a cgroup
soft limit. Setting --memory too low will cause the process to OOM inside the VM.
> There is no "unlimited" mode: Docker's --memory 0 (no limit) maps to the Apple
Container default of 1 GiB, not host RAM. To give a container more than 1 GiB,
always pass an explicit --memory value.
In Docker Compose:
services:
kafka:
image: confluentinc/cp-kafka
mem_limit: 2g
redis:
image: redis:alpine
mem_limit: 256m
DNS upstream
Socktainer runs an embedded DNS server that resolves container names and forwards other
multi-label names (e.g. github.com) to an upstream resolver; unknown single-label names are
answered locally (NXDOMAIN/NODATA) and never forwarded. By default the upstream is the IPv4 gateway of the
default network (the vmnet gateway, e.g. 192.168.64.1), falling back to 1.1.1.1 if the
gateway cannot be read.
On some managed Macs the vmnet gateway does not answer DNS queries, so containers on named
networks cannot resolve external names. The override only affects the embedded server, so it
applies to containers on named networks (including Docker Compose); containers on the
default network still query the vmnet gateway directly unless an upstream is configured (see below).
Point it at a resolver that already runs on the host (macOS has none on 127.0.0.1:53 by
default), for example a local DNS proxy installed by security or VPN software, or one you run
yourself. The address must be an IPv4 literal, with an optional port (default 53):
socktainer --dns-upstream 127.0.0.1
SOCKTAINER_DNS_UPSTREAM=127.0.0.1:5353 socktainer
Use auto to follow the Mac's own DNS resolvers instead of naming one. Socktainer then forwards
to the global default resolvers (from SystemConfiguration, falling back to /etc/resolv.conf),
tries them in order if one answers SERVFAIL or REFUSED, and picks up changes such as a VPN
connecting or a network switch without a restart. Only IPv4 resolvers are used, and scoped or
split DNS (/etc/resolver/*, per-domain VPN resolvers) is not consulted; with no usable resolver
it uses the default described above.
socktainer --dns-upstream auto
SOCKTAINER_DNS_UPSTREAM=auto socktainer
When an upstream is configured (an address or auto), containers on the default network get
the embedded DNS server's forwarder as their nameserver too, so they use the same upstream, and
an explicit --dns / HostConfig.Dns (for example Compose dns:) is kept instead of being
replaced by the forwarder.
Do not point it at socktainer's own DNS port; that configuration is ignored with an error.
The --dns-upstream flag takes precedence over SOCKTAINER_DNS_UPSTREAM, which takes
precedence over gateway auto-detection. An invalid --dns-upstream value stops startup; an
invalid SOCKTAINER_DNS_UPSTREAM value is ignored with a warning. If you run socktainer as a
Homebrew service, the service does not read your shell environment, so set the variable in the
service's environment or run socktainer manually.
Volume compatibility — Postgres
Apple Container's EXT4 volumes always contain /lost+found, which causes
initdb to fail with "directory exists but is not empty". Socktainer
automatically removes it when a Postgres container is created, before
initdb runs.
Opt out — set SOCKTAINER_CLEAN_VOLUMES=false globally, or label a
specific volume with socktainer.clean-volumes=false.
Loopback URLs in environment variables
Like Docker, Socktainer passes environment values through unchanged, so
127.0.0.1 inside a container refers to the container itself. To have
URL-form values (scheme://127.0.0.1:PORT or [email protected]:PORT) rewritten
to the network gateway for a container on a named network, opt in with the
socktainer.rewrite-loopback=true container label.
Peer hostnames in environment variables
Container hostnames in environment values are also left unchanged and resolved
through DNS at runtime. To have connection-string positions
(scheme://NAME:PORT, user@NAME:PORT or host=NAME) rewritten to the
current IP of the container that owns NAME, for a container on a named
network, opt in with the socktainer.rewrite-peer-hostnames=true container
label. The IP is captured when the container is created, so it goes stale if
that peer is later re-created with a new address.
Building from Source 🏗️
Prerequisites
- Swift 6.4
- Xcode with the Swift 6.4 toolchain (select the correct toolchain if installed in a custom location)
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
Build & Run
- Build the project:
make
- (Optional) Format the code:
make fmt
- Run the debug binary:
.build/arm64-apple-macosx/debug/socktainer
The server will create the socket at $HOME/.socktainer/container.sock.
Testing ✅
Run unit tests:
make test
Contributing 🤝
We welcome contributions!
Workflow
- Fork the repository and create a feature branch 🌿
- Open a PR against
mainwith a clear description 📝 - Add or update tests for new behavior (see
Tests/socktainerTests) ✔️ - Keep changes small and focused. Document API or behavioral changes in the PR description 📚
Developer Notes 🧑💻
- Code organization under
Sources/socktainer/:
Routes/ — Route handlers 🛣️
- Clients/ — Client integrations 🔌
- Utilities/ — Helper utilities 🧰
- Document any public API or CLI changes in this README 📝
Piping I/O to container processes
When passing I/O to ContainerClient.createProcess(stdio:) or ContainerClient.bootstrap(id:stdio:), do not use Foundation's Pipe(). Use StdioPipes from Sources/socktainer/Utilities/DockerConnectionUtility.swift instead.
Background: on Unix, every open file/socket/pipe is identified by a small integer called a file descriptor (fd). Apple's APIs dup the fds you pass into the container and then immediately close your originals. Foundation's Pipe doesn't know this happened — when it's eventually garbage-collected, it tries to close() the same fd number again. By then, that number may have been recycled for a NIO HTTP socket, so the double-close silently kills an active connection, corrupting the event loop and causing hard-to-reproduce crashes under concurrent load (issue #107).
StdioPipes centralises allocation, EMFILE validation, and cleanup:
guard let pipes = StdioPipes.make([.stdin, .stdout, .stderr]) else { // or make(.all)
throw Abort(.internalServerError, reason: "Failed to create I/O pipes")
}
let process: ClientProcess
do {
process = try await ContainerClient().createProcess(..., stdio: pipes.stdioArray)
} catch {
pipes.closeAll() // Apple never received the fds — close all 6
throw error
}
do {
try await process.start()
} catch {
pipes.closeAfterHandoff() // Apple owns stdin.read, stdout.write, stderr.write
throw error
}
// Use pipes.stdout?.read, pipes.stderr?.read, pipes.stdin?.write in tasks
Ownership rules:
- stdout/stderr: Apple closes
.write. You close.readwhen the reader task ends. - stdin: Apple closes
.read. You close.writewhen done sending input. StdioPipes.make()closes any partial pipes on EMFILE and returnsnil— alwaysguard let.
make test includes a lint-pipes check that fails if = Pipe() appears in any source file other than the one legitimate exception (ClientRegistryService.swift, which uses Foundation's own Process, not Apple Container APIs).
Security & Limitations ⚠️
- Intended for local development and experimentation 🏠
- Running third-party container workloads carries inherent risks. Review sandboxing and container configurations 🔒
- Docker API compatibility is partial, focused on commonly used endpoints. See
Sources/socktainer/Routes/for implemented routes - Private registry auth currently depends on Apple
containerbehavior. If login succeeds but private pulls/builds still fail, a manual workaround may be required. See apple/container#816 comment 3534438608 and comment 3503618765. docker run --privilegedhas no direct Apple Containerization equivalent — Apple Container has no privileged mode — but socktainer maps it onto the closest available approximation: granting every capability (--cap-add=ALL), the same grant its own builder container uses. This is enough to unblock common uses of--privileged(e.g. buildx'sdocker-containerdriver rbind-mounting its build context), but it is not a full equivalent of real privileged mode — device access, seccomp, and AppArmor are unaffected. Use granular--cap-add/--cap-drop(and--read-only,--sysctl) directly if you need finer control than "all or nothing."docker run --cpusis honored, but Apple Container allocates a whole vCPU count to each container's VM rather than throttling a shared kernel's CFS quota. A fractional value is floored to the nearest whole core (minimum 1) — e.g.--cpus=1.5gets 1 vCPU,--cpus=0.5still gets 1.--cpu-shares(relative weighting) and--cpu-period/--cpu-quotahave no equivalent and are not applied.- Bind-mounting
/var/run/docker.sock(e.g.-v /var/run/docker.sock:/var/run/docker.sock, used by tools like Supabase'svectorlog collector) is transparently relayed to socktainer's own Docker-compatible API, rather than dropped. This matches Docker's own behavior for the same bind mount, and carries the same well-known risk: any container that requests this mount gets full control of every other container socktainer manages, not just itself — the same exposure Docker itself has always had with this idiom, not something new to socktainer. This scales with the number of containers that request the mount, since each gets its own fully-privileged, independent connection. docker exportstreams the container's root filesystem; exporting a running container yields a volatile snapshot, same as Docker. One visible difference: the tar contains no/.dockerenv— Docker's daemon fabricates that file inside every container at start, Apple Container does not. Tools that probe/.dockerenvto detect "am I inside a container" won't find it in filesystems exported from socktainer.docker run --restartis honored (no,always,unless-stopped,on-failure[:max-retries]), matching moby's restart-manager behavior closely, including its quirks:
always restores a previously started instance, unless-stopped preserves a manual stop, and stopped on-failure instances are restored when a durable nonzero exit code and retry allowance remain (including after a manual stop); instances stay stopped when the exit code or bounded retry budget is unavailable.
- Startup recovery uses durable instance identity and start evidence: running managed instances are adopted without another bootstrap, while stopped legacy instances lacking start evidence require an explicit start.
docker updatesupports restart policies only (--restart). CPU and memory limits cannot change after create — Apple Container runs each container in a VM whose resources are fixed at boot. Resource-only updates return an error; a restart-policy update combined with resource flags applies the policy and returns a warning for the ignored fields. Updated policies are stored durably and, like create-time policies, are honored by startup recovery after a daemon restart.docker loadaccepts tarballs from real Docker (plain, gzip or zstd compressed). Index entries whose blobs are not in the tarball are dropped on load —docker saveon real Docker ships only the pulling platform's blobs while keeping the full multi-platform index, so only that platform is imported.docker saveworks for images that were loaded from a tarball, and thedocker save | docker loadround-trip is supported. It fails withContentStore missing blob datafor registry-pulled images: Apple's Containerization pull stores the image's full multi-platform index but downloads only the local platform's blobs, and save exports the whole index (platform limitation).docker renameworks only for containers that have never been started, which covers Compose recreation (it renames its new replacement before starting it). Apple Container has no rename and names a container by its id, so socktainer recreates the container under the new name, keeping its Docker ID. A container that has run keeps a writable root filesystem that recreating would lose, so renaming it returns409 Conflict.docker pause/docker unpauseare not supported — there is no freezer/checkpoint equivalent for Apple Container VMs.docker network connect/disconnectare accepted as no-ops: Virtualization.framework offers no NIC hotplug and Apple Container has no post-create attach API, so network membership is fixed at container create. Containers on user-created networks reach each other by name through socktainer's DNS, which covers the common Compose use.- Static container IPs (
--ip, IPAM per-container config) cannot be honored: Apple Container assigns addresses from a rotating allocator with no way to request a specific one. Name-based discovery via socktainer DNS is the supported alternative; addresses stay stable for a container's lifetime. - Not yet implemented (endpoints answer an explicit error instead of pretending):
docker commit,docker diff,docker search,docker top, andGET /distribution/{name}/json.
Docker Compose — inter-service DNS
Socktainer registers service names in its DNS server so Compose services can reach each other by name. Two aliases are created per service:
| Alias | Example | Description |
|---|---|---|
| service | db | Short form — works within a single project |
| service.project | db.myapp | Project-qualified — unique across concurrent projects |
Set the project name explicitly via name: at the top of your Compose file
(otherwise Docker Compose derives it from the directory name):
name: myapp # sets com.docker.compose.project=myapp
services:
web:
image: nginx:alpine
# can reach the database as 'db' or 'db.myapp'
db:
image: postgres:17
environment:
POSTGRES_PASSWORD: secret
Note: Apple Container uses a single global hostname namespace. Two
Compose projects running simultaneously with identically-named services
(e.g. both have a db service) will share the short-form alias — last
started wins. Use the qualified form (db.myapp) to resolve unambiguously.
Container-to-container connections fail with EHOSTUNREACH
If inter-container connections start failing with no route to host / EHOSTUNREACH after heavy use (many networks created and destroyed), Apple Container's vmnet state has degraded — reset it with container system stop && container system start, then restart socktainer.
Internal networks
Use docker network create --internal or Compose's internal: true to create a network without external connectivity, backed by Apple Container's host-only mode. Network inspect reports Internal: true; the driver remains nat.
Network subnets (IPAM)
Socktainer pins a stable subnet on each network it creates so that inter-container DNS keeps working across a container system restart (an unpinned network's subnet is reassigned by vmnet on restart, which would leave containers' DNS nameservers pointing at a dead address). An explicit --subnet / Compose ipam.config.subnet is honored; otherwise a free 192.168.x.0/24 is chosen automatically.
IPAM.Config fields other than Subnet — Gateway, IPRange, and AuxiliaryAddresses — are not supported by the Apple Container backend (the gateway is always the subnet's .1 and addresses are allocated by vmnet). They are ignored, and a WARNING is logged when requested.
Note: networks created before this behavior shipped are not pinned retroactively — recreate them (docker compose down && docker compose up) to get a stable subnet.
Label key normalization
Apple Container only accepts lowercase label keys matching a-z0-9?. Docker allows mixed-case, underscores, and other characters. Socktainer automatically normalizes label keys at create time:
- Uppercase → lowercase (
sessionId→sessionid) - Underscores → hyphens (
my_key→my-key) - Other invalid characters are dropped
- An
INFOlog is emitted for every key that is changed - A
WARNINGis logged when a key becomes empty after normalization (dropped) or when two keys normalize to the same string (collision, last value wins)
socktainer.label-original-keys) that is stored alongside the normalized keys and stripped from all API responses. As a result, docker inspect, filter lookups, and Go-template label access all return and match the original key exactly:
# Works — original key is restored transparently
docker inspect --format '{{index .Config.Labels "MyApp"}}' <container>
docker ps --filter label=MyApp=value
The one edge case: if two keys normalize to the same string (e.g. MyKey and mykey), the last one wins — a WARNING is logged so the loss is visible in Socktainer's output.
Community 💬
Join the Socktainer community to ask questions, share ideas, or get help:
- Website: socktainer.github.io – documentation and project news
- Discord: discord.gg/Pw9VWKcUEt – chat in real time with contributors and users
- GitHub Discussions: socktainer/discussions – ask questions or propose features
- GitHub Issues: socktainer/issues – report bugs or request features
License 📄
See the LICENSE file in the repository root.
Acknowledgements 🙏
- Built using Apple containerization libraries 🍏
- Enables Docker CLI and other Docker clients to interact with local macOS containers 🐳💻