• Socktainer 🚢
  • Quick Start ⚡
    • Launch socktainer 🏁
    • Using Docker CLI 🐳
  • Key Features ✨
  • Requirements 📋
  • Installation 🛠️
    • Homebrew
      • Stable Release
      • Pre Release
    • GitHub Releases
  • Usage 🚀
  • 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 🐳💻.

Podman Desktop Apple Container extension uses socktainer to visualize Apple containers/images in Podman Desktop.

Get started with socktainer CLI in just a few commands:

./socktainer
FolderWatcher] Started watching $HOME/Library/Application Support/com.apple.container
[ NOTICE ] Server started on http+unix: $HOME/.socktainer/container.sock
...

Export the socket path as DOCKER_HOST:

export DOCKER_HOST=unix://$HOME/.socktainer/container.sock
docker ps        # List running containers
docker ps -a     # List all containers
docker images    # List available images

Or inline without exporting:

DOCKER_HOST=unix://$HOME/.socktainer/container.sock docker ps
DOCKER_HOST=unix://$HOME/.socktainer/container.sock docker images

• Built on Apple’s Container Framework 🍏
• Provides Docker REST API compatibility 🔄 (partial)
• Listens on a Unix domain socket $HOME/.socktainer/container.sock
• Supports container lifecycle operations: inspect, stop, remove 🛠️
• Supports image listing, pulling, deletion, logs, health checks. Exec without interactive mode 📄
• Broadcasts container events for client liveness monitoring 📡

• macOS 26 (Tahoe) on Apple Silicon (arm64) Apple’s container APIs only work on arm64 Macs 🍏💻
• Apple Container 0.6.0

socktainer is shipped via a homebrew tap:

brew tap socktainer/tap

Install the official release:

brew install socktainer

Install development release:

brew install socktainer-next

Download from socktainer releases page the zip or binary. Ensure the binary has execute permissions (+x) before running it.

Refer to Quick Start above for immediate usage examples.

• Swift 6.2 (requirements from Apple container)
• Xcode 26 (select the correct toolchain if installed in a custom location)

sudo xcode-select --switch /Applications/Xcode_26.0.0.app/Contents/Developer
# or
sudo xcode-select -s /Applications/Xcode-26.app/Contents/Developer

1. Build the project:

make

2. (Optional) Format the code:

make fmt

3. Run the debug binary:

.build/arm64-apple-macosx/debug/socktainer

The server will create the socket at $HOME/.socktainer/container.sock.

Run unit tests:

make test

We welcome contributions!

1. Fork the repository and create a feature branch 🌿
2. Open a PR against main with a clear description 📝
3. Add or update tests for new behavior (see Tests/socktainerTests) ✔️
4. Keep changes small and focused. Document API or behavioral changes in the PR description 📚

• Code organization under Sources/socktainer/:
  • Routes/ — Route handlers 🛣️
  • Clients/ — Client integrations 🔌
  • Utilities/ — Helper utilities 🧰
• Document any public API or CLI changes in this README 📝

• 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 container behavior. If login succeeds but private pulls/builds still fail, a manual workaround may be required. See apple/container#816 comment 3534438608 and comment 3503618765.

Join the Socktainer community to ask questions, share ideas, or get help:

• 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

See the LICENSE file in the repository root.

• Built using Apple containerization libraries 🍏
• Enables Docker CLI and other Docker clients to interact with local macOS containers 🐳💻