gocker

gocker

Docker-compatible CLI and API daemon for Apple Container on macOS 26+. Also runs natively on Linux via containerd/nerdctl.

Every container runs as a lightweight Linux microVM backed by Apple's Virtualization.framework — hardware-level isolation, not just namespaces.

Why gocker?

Requirements

• macOS 26+ (Tahoe) on Apple Silicon, or Linux with containerd + nerdctl
• Apple's container CLI (macOS) — installed automatically via gocker setup

Install

# Homebrew (recommended)
brew tap lunguini/tap
brew install gocker

# Or with Go
go install github.com/lunguini/gocker@latest

Getting Started

# First-run wizard — see "Setup" below for what it asks
gocker setup

# Run a container
gocker run ubuntu:latest echo "hello from a microVM"

# Run an interactive container
gocker run -it ubuntu:latest /bin/bash

Setup

gocker setup is the first-run flow. It checks prerequisites, installs Apple Container CLI if missing, and then runs a short interactive wizard:

• Isolation mode — full / hybrid / shared (see Isolation Modes). The prompt explains the trade-offs.
• VM resources — CPU and memory for the shared VM, defaulted from your host specs and chosen mode.
• Shell integration (opt-in) — adds DOCKER_HOST and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE to your shell rc (bash / zsh / fish), inside sentinel-marked blocks. Skipped if your rc already exports DOCKER_HOST to the gocker socket.
• Docker context (opt-in) — creates a gocker docker context and makes it active, so docker commands route through gocker.

Re-running gocker setup is safe — existing config is preserved unless you change an answer.

For CI / non-interactive environments:

gocker setup --yes   # uses 'shared' isolation, skips shell + docker-context prompts

Usage

gocker mirrors Docker's CLI interface:

gocker run -d --name web -p 8080:80 nginx     # Run in background
gocker ps                                       # List containers
gocker logs web                                 # View logs
gocker exec -it web /bin/sh                     # Exec into container
gocker stop web                                 # Stop container
gocker rm web                                   # Remove container

Images, networks, and volumes work the same way:

gocker pull ubuntu:latest
gocker images
gocker network create mynet
gocker volume create mydata

Use --format json on any command for JSON output.

Compose

Run multi-container applications with standard docker-compose.yml files:

gocker compose up                 # Start all services
gocker compose up -d              # Start in background
gocker compose ps                 # List service containers
gocker compose logs               # View all logs
gocker compose logs api           # View logs for one service
gocker compose restart redis      # Restart a service
gocker compose down               # Stop and remove everything
gocker compose down -v            # Also remove volumes

Supports -f <file> for custom compose file paths and -p <name> for project name override.

AI Agent Sandboxing

The killer feature. Run AI agents in hardware-isolated microVMs with host configs synced automatically:

# Run Claude Code in a sandbox (mounts current dir as /workspace)
gocker sandbox run claude ./

# Run with a custom name
gocker sandbox run claude ./ --name my-project

# Run in background
gocker sandbox run claude ./ -d

# Manage sandboxes
gocker sandbox ls
gocker sandbox attach my-project
gocker sandbox logs my-project
gocker sandbox stop my-project
gocker sandbox rm my-project

Sandboxes automatically:

• Mount your workspace into the VM
• Sync host Claude settings (plugins, marketplaces) with sandbox-safe defaults
• Sync Claude Code sessions — /resume works across host and sandbox
• Forward ANTHROPIC_API_KEY from your environment
• Allocate 4GB memory for Claude Code

Session sync can be disabled in ~/.gocker/config.yaml:

sandbox:
  syncClaudeSession: false

Isolation Modes

Pick the mode during gocker setup, or edit ~/.gocker/config.yaml directly:

isolation: hybrid  # full | hybrid | shared

Override per-command: gocker --isolation full compose up

Docker API & Portainer

gocker includes a Docker-compatible REST API daemon. Existing Docker tools like Portainer, lazydocker, and Testcontainers work out of the box.

Portainer setup

# Start the gocker API daemon
gocker daemon start

# Create volume and run Portainer
gocker volume create portainer_data
gocker run -d -p 9443:9443 --name portainer -v ~/.gocker/gocker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:sts

# Open https://localhost:9443

Note: Mount ~/.gocker/gocker.sock (not /var/run/docker.sock) as the host-side socket path. The container-side path stays /var/run/docker.sock since that's where tools expect it.

Daemon management

gocker daemon start          # Start API daemon
gocker daemon stop           # Stop API daemon
gocker daemon status         # Show daemon + shared VM status
gocker daemon vm status      # Shared VM status (hybrid/shared modes)
gocker daemon vm stop        # Stop the shared VM

AI Agent Integration

Get a complete CLI reference optimized for AI agents — every command, flag, and example in one output:

gocker ai

This outputs a structured reference that agents can consume directly, plus workspace context (detected compose files, running containers, Dockerfiles). Pipe it into a system prompt, paste it into CLAUDE.md, or let your agent call it at the start of a session.

# Add to a project's CLAUDE.md
gocker ai >> CLAUDE.md

# Use in a prompt
gocker ai | claude --prompt "help me set up a postgres + redis stack"

Migrating from Docker

Most Docker commands work by replacing docker with gocker:

# Docker                                    # gocker
docker run -d -p 80:80 nginx                gocker run -d -p 80:80 nginx
docker compose up -d                        gocker compose up -d
docker ps                                   gocker ps
docker exec -it myapp sh                    gocker exec -it myapp sh
docker build -t myimg .                     gocker build -t myimg .

Known differences

Socket path

Docker tools expect a socket at /var/run/docker.sock. The easiest way to wire this up is to run gocker setup and accept the shell-integration and docker-context prompts — they handle DOCKER_HOST, TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE, and the docker CLI context for you.

Manual alternatives:

# Export so docker / SDK clients pick it up
export DOCKER_HOST=unix://$HOME/.gocker/gocker.sock

Or mount the gocker socket when running tools inside a container:

-v ~/.gocker/gocker.sock:/var/run/docker.sock

Shell Completions

# Bash
gocker completion bash >> ~/.bashrc

# Zsh
gocker completion zsh >> ~/.zshrc

# Fish
gocker completion fish > ~/.config/fish/completions/gocker.fish

Benchmarks

Compare gocker vs Docker Desktop performance:

make benchmark

Measures container startup time, image pull speed, ps latency, memory overhead, and binary size. Results are averaged over multiple runs. Only compares against Docker if it's installed — otherwise shows gocker results only.

Building

make build          # Build the binary
make build-linux    # Cross-compile for Linux/arm64
make install        # Build and install to /usr/local/bin
make test           # Run tests
make lint           # Run linter
make smoke          # End-to-end smoke test
make benchmark      # Performance comparison vs Docker Desktop

Template Images

make template-push-claude   # Build and push Claude sandbox image
make template-push-base     # Build and push gocker-base shared VM image
make template-push          # Build and push all template images

Roadmap

• Core container commands (run, ps, stop, rm, exec, logs, inspect, start)
• Image management (pull, push, images, rmi, build)
• Network management (network create/ls/rm/connect/disconnect)
• Volume management (volume create/ls/rm/inspect)
• Docker REST API daemon on Unix socket (gocker daemon start)
• AI sandbox — gocker sandbox run claude ./ with config sync
• Interactive setup wizard (gocker setup installs Apple Container CLI, configures isolation mode + VM resources, optionally wires shell + docker context; --yes for CI)
• Template images published to Docker Hub
• gocker compose up/down/ps/logs/restart with standard docker-compose.yml
• Smoke test suite (make smoke) for end-to-end CLI validation
• Golden file parser tests for Apple CLI output format changes
• Configurable VM isolation modes (full, hybrid, shared) with shared VM support
• Config file support (~/.gocker/config.yaml)
• Cross-platform runtime: Apple Container (macOS) + nerdctl (Linux)
• Shell completions (gocker completion bash/zsh/fish)
• Gocker-base image for shared VM (make template-push-base)
• Docker API compatibility (Portainer, lazydocker, Testcontainers)
• Performance benchmarks (make benchmark)
• AI agent CLI reference (gocker ai)
• Claude Code session sync across host and sandbox (/resume works)
• GoReleaser + GitHub Actions release workflow
• Homebrew formula (brew tap lunguini/tap && brew install gocker) Planned work is tracked as GitHub issues with the roadmap label: github.com/lunguini/gocker/issues?q=label%3Aroadmap.

Current top items: Docker API /containers/{id}/attach for docker run -it, /containers/{id}/wait for docker run -d exit codes, image-pull performance tuning, sandbox network-policy enforcement, and Codex/Gemini agent templates.

License

Apache 2.0