{"id":46631246,"url":"https://github.com/us/mocker","last_synced_at":"2026-04-25T10:01:13.175Z","repository":{"id":342899344,"uuid":"1175493743","full_name":"us/mocker","owner":"us","description":"Docker-compatible container CLI built on Apple's Containerization framework. Same commands, same flags — mocker run, ps, stop, build, compose, stats — all working on macOS 26.","archived":false,"fork":false,"pushed_at":"2026-04-25T08:14:04.000Z","size":237,"stargazers_count":133,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-25T09:30:44.912Z","etag":null,"topics":["apple-containerization","cli","compose","containerization","containers","docker","macos","macos26","swift","swift-package-manager"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/us.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T19:36:47.000Z","updated_at":"2026-04-25T08:14:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/us/mocker","commit_stats":null,"previous_names":["us/mocker"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/us/mocker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/us%2Fmocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/us%2Fmocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/us%2Fmocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/us%2Fmocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/us","download_url":"https://codeload.github.com/us/mocker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/us%2Fmocker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32257755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-containerization","cli","compose","containerization","containers","docker","macos","macos26","swift","swift-package-manager"],"created_at":"2026-03-08T00:02:22.905Z","updated_at":"2026-04-25T10:01:13.156Z","avatar_url":"https://github.com/us.png","language":"Swift","readme":"\u003cdiv align=\"center\"\u003e\n\n# Mocker\n\n**A Docker-compatible container management tool built on Apple's Containerization framework**\n\n[![Swift](https://img.shields.io/badge/Swift-6.0-orange.svg)](https://swift.org)\n[![Platform](https://img.shields.io/badge/Platform-macOS%2026%2B-blue.svg)](https://developer.apple.com/macos/)\n[![License](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)\n[![Swift Package Manager](https://img.shields.io/badge/SPM-compatible-brightgreen.svg)](Package.swift)\n\n[English](README.md) · [简体中文](README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\nMocker is a **Docker-compatible CLI + Compose** tool that runs natively on macOS using Apple's [Containerization](https://developer.apple.com/documentation/containerization) framework (macOS 26+). It speaks the same language as Docker — same commands, same flags, same output format — so your existing scripts and muscle memory just work.\n\n## Just replace `docker` with `mocker`\n\n```bash\n# Before\ndocker compose up -d\ndocker ps\ndocker logs my-app\ndocker exec -it my-app sh\n\n# After — same commands, native Apple runtime, no Docker Desktop\nmocker compose up -d\nmocker ps\nmocker logs my-app\nmocker exec -it my-app sh\n```\n\nYour existing `docker-compose.yml` works as-is.\n\n## What's New\n\n### v0.2.1 — Nested virtualization\n- **`--virtualization` / `--kernel`** for `mocker run` and `mocker create` — expose nested virtualization to containers (closes #4)\n\n### v0.2.0 — Ground Truth\n- **Honesty layer** — unsupported commands return explicit errors instead of silently mutating state\n- **Security**: shell-injection fixes in `copyToContainer` and compose hostname injection\n- Forward Apple CLI flags in `run` (`-i`, `-t`, `--cidfile`, `--rm`, `--platform`, ...) and `build` (`--label`, `--quiet`, `--progress`, `--output`)\n- Test infrastructure: `ProcessRunner` protocol + 16 new tests (42 total)\n\n### v0.1.9 — Full Docker CLI Flag Compatibility\n- **111 commands/subcommands** with Docker-matching flags\n- `run`/`create`: ~50 new flags (`--attach`, `--cpu-shares`, `--gpus`, `--init`, `--memory`, `--privileged`, `--restart`, `--shm-size`, `--ulimit`, etc.)\n- `build`: ~25 BuildKit/Buildx flags (`--cache-from`, `--load`, `--push`, `--secret`, `--ssh`, etc.)\n- `compose`: ~200+ flags across 22 subcommands\n- New commands: `commit`, `container prune`, `container export`, `image rm/inspect/prune`\n- Full [COMMANDS.md](COMMANDS.md) reference and [CHANGELOG.md](CHANGELOG.md) added\n\n### v0.1.8 — `--env-file` support\n- **`mocker run --env-file .env`** — load environment variables from file, just like Docker\n\n### v0.1.7 — Compose improvements \u0026 `--rm` flag\n- **`mocker run --rm`** — auto-remove container on exit\n- `compose.yaml` / `compose.yml` recognized as default compose file\n- Compose `${VAR:-default}` variable substitution fix\n\n\u003e See [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n## Features\n\n- **Docker CLI compatible** — `run`, `ps`, `stop`, `rm`, `exec`, `logs`, `build`, `pull`, `push`, `images`, `tag`, `rmi`, `inspect`, `stats`\n- **Network management** — `network create/ls/rm/inspect/connect/disconnect`\n- **Volume management** — `volume create/ls/rm/inspect`\n- **Docker Compose v2** — `compose up/down/ps/logs/restart` with dependency ordering\n- **MenuBar GUI** — Native SwiftUI app *(coming soon)*\n- **JSON state persistence** — All metadata stored in `~/.mocker/`\n- **Swift 6 concurrency** — Full actor-based thread safety throughout\n\n\u003e **Compatibility note:** Mocker parses all Docker CLI flags for drop-in compatibility, but some flags are not supported by Apple's Containerization runtime and will produce a warning or error. See [COMMANDS.md](COMMANDS.md) for details on which commands are fully functional vs unsupported.\n\n## Requirements\n\n| Component | Version |\n|-----------|---------|\n| macOS | 26.0+ (Sequoia) |\n| Swift | 6.0+ |\n| Xcode | 16.0+ |\n\n\u003e **Note:** The Apple Containerization framework requires macOS 26 on Apple Silicon. Intel Macs are not supported.\n\n## Installation\n\n### Homebrew (Recommended)\n\n```bash\nbrew tap us/tap\nbrew install mocker\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/us/mocker.git\ncd mocker\nswift build -c release\ncp .build/release/mocker /usr/local/bin/mocker\n```\n\n## Quick Start\n\n```bash\n# Pull an image\nmocker pull nginx:1.25\n\n# Run a container\nmocker run -d --name webserver -p 8080:80 nginx:1.25\n\n# List running containers\nmocker ps\n\n# View logs\nmocker logs webserver\n\n# Stop and remove\nmocker stop webserver\nmocker rm webserver\n```\n\n## Usage\n\n### Container Lifecycle\n\n```bash\n# Run with environment variables and volumes\nmocker run -d \\\n  --name myapp \\\n  -p 8080:80 \\\n  -e APP_ENV=production \\\n  --env-file .env \\\n  -v /host/data:/app/data \\\n  myimage:latest\n\n# Run interactively (foreground)\nmocker run --name temp alpine:latest\n\n# Force remove a running container\nmocker rm -f myapp\n\n# Execute a command inside a running container\nmocker exec myapp env\n\n# Follow logs\nmocker logs -f myapp\n```\n\n### Images\n\n```bash\n# Pull specific tag\nmocker pull postgres:15\n\n# List images\nmocker images\n\n# List image IDs only\nmocker images -q\n\n# Tag an image\nmocker tag alpine:latest my-registry.io/alpine:v1\n\n# Remove an image\nmocker rmi my-registry.io/alpine:v1\n\n# Build from Dockerfile\nmocker build -t myapp:latest .\n\n# Push to registry\nmocker push my-registry.io/myapp:latest\n```\n\n### Inspect \u0026 Stats\n\n```bash\n# Inspect container (JSON output)\nmocker inspect myapp\n\n# Inspect multiple targets\nmocker inspect container1 container2 alpine:latest\n\n# Resource usage stats\nmocker stats --no-stream\n```\n\n### Networks\n\n```bash\n# Create a network\nmocker network create mynet\n\n# List networks\nmocker network ls\n\n# Connect a container\nmocker network connect mynet myapp\n\n# Disconnect\nmocker network disconnect mynet myapp\n\n# Inspect\nmocker network inspect mynet\n\n# Remove\nmocker network rm mynet\n```\n\n### Volumes\n\n```bash\n# Create a named volume\nmocker volume create pgdata\n\n# List volumes\nmocker volume ls\n\n# Inspect (shows mountpoint)\nmocker volume inspect pgdata\n\n# Remove\nmocker volume rm pgdata\n```\n\n### Docker Compose\n\n```bash\n# Start all services (detached)\nmocker compose -f docker-compose.yml up -d\n\n# List compose containers\nmocker compose -f docker-compose.yml ps\n\n# View logs for a service\nmocker compose -f docker-compose.yml logs web\n\n# Restart a service\nmocker compose -f docker-compose.yml restart api\n\n# Tear down\nmocker compose -f docker-compose.yml down\n```\n\nExample `docker-compose.yml`:\n\n```yaml\nversion: \"3.8\"\n\nservices:\n  web:\n    image: nginx:1.25\n    ports:\n      - \"8080:80\"\n    depends_on:\n      - api\n\n  api:\n    image: myapp:latest\n    environment:\n      - DB_HOST=db\n      - DB_PORT=5432\n    depends_on:\n      - db\n\n  db:\n    image: postgres:15\n    environment:\n      POSTGRES_PASSWORD: secret\n      POSTGRES_DB: myapp\n    volumes:\n      - pgdata:/var/lib/postgresql/data\n\nvolumes:\n  pgdata:\n```\n\n### System\n\n```bash\n# System information\nmocker system info\n\n# Remove stopped containers and unused resources\nmocker system prune -f\n```\n\n## Architecture\n\n```\nmocker/\n├── Sources/\n│   ├── MockerKit/          # Shared core library\n│   │   ├── Models/         # Data types (ContainerInfo, ImageInfo, ...)\n│   │   ├── Config/         # MockerConfig (~/.mocker/ paths)\n│   │   ├── Container/      # ContainerEngine + ContainerStore (actor)\n│   │   ├── Image/          # ImageManager + ImageStore (actor)\n│   │   ├── Network/        # NetworkManager (actor)\n│   │   ├── Volume/         # VolumeManager (actor)\n│   │   └── Compose/        # ComposeFile parser + ComposeOrchestrator\n│   ├── Mocker/             # CLI executable\n│   │   ├── Commands/       # One file per command group\n│   │   └── Formatters/     # TableFormatter, JSON output\n│   └── MockerApp/          # SwiftUI MenuBar app (macOS 26+)\n│       ├── MenuBar/\n│       ├── ViewModels/\n│       └── Views/\n└── Tests/\n    ├── MockerKitTests/     # Unit tests for core library\n    └── MockerTests/        # CLI integration tests\n```\n\n### Key Design Decisions\n\n| Concern | Approach |\n|---------|----------|\n| Thread safety | All engines/managers are `actor` types |\n| Persistence | JSON files in `~/.mocker/{containers,images,networks,volumes}/` |\n| CLI parsing | `swift-argument-parser` with `AsyncParsableCommand` |\n| YAML parsing | `Yams` library |\n| Compose naming | Docker v2 convention: `projectName-serviceName-1` (hyphen separator) |\n| JSON output | Always wrapped in array `[{...}]`, matching Docker's `inspect` format |\n\n## Data Directory\n\nMocker stores all state in `~/.mocker/`:\n\n```\n~/.mocker/\n├── containers/   # Container metadata (one JSON file per container)\n├── images/       # Image metadata\n├── networks/     # Network metadata\n└── volumes/      # Volume metadata + actual data directories\n    └── pgdata/\n        └── _data/\n```\n\n## Docker Compatibility\n\nMocker aims for full CLI compatibility with Docker. Key behaviors matched:\n\n- Error messages: `Error response from daemon: ...`\n- `inspect` always returns a JSON array, even for a single object\n- `pull` idempotency: re-pulling an existing image shows \"Image is up to date\"\n- Compose container naming: `project-service-1` (hyphen, not underscore)\n- `stop` and `rm` echo back the identifier provided by the user\n- Short IDs are 12 characters (first 12 of full 64-char hex ID)\n\n## Building \u0026 Testing\n\n```bash\n# Build all targets\nswift build\n\n# Run all tests\nswift test\n\n# Run specific test suite\nswift test --filter MockerKitTests\n\n# Run CLI directly\nswift run mocker --help\n```\n\n## Performance\n\nBenchmarks run on Apple M-series, macOS 26 (`hyperfine --warmup 5 --runs 15`):\n\n| Tool | Container startup | vs Docker |\n|------|:-----------------:|:---------:|\n| Docker Desktop | 320 ms | baseline |\n| Apple `container` CLI | 1,030 ms | 3.2× slower |\n| **Mocker** | **1,153 ms** | **3.6× slower** |\n\nApple's VM-per-container model trades startup time for stronger isolation — every container gets its own lightweight Linux VM. Mocker adds only ~120 ms of management overhead on top of Apple's runtime.\n\n**CPU \u0026 Memory throughput** (sysbench inside container, 30s run):\n\n| Metric | Docker | Apple Container |\n|--------|:------:|:---------------:|\n| CPU events/s | 7,958 | 7,894 |\n| Memory throughput | 13,340 MiB/s | 13,119 MiB/s |\n\nRaw compute performance is equivalent — the VM boundary has negligible overhead for CPU and memory workloads.\n\n## How It Works\n\nMocker delegates to Apple's `container` CLI for container lifecycle (run, stop, exec, logs, build).\nImage operations (pull, list, tag, rmi) use `Containerization.ImageStore` directly. This hybrid\napproach gives you a fully working Docker-compatible tool on macOS 26 today:\n\n| Operation | Backend |\n|-----------|---------|\n| `run`, `stop`, `exec`, `logs` | `/usr/local/bin/container` subprocess |\n| `build` | `container build` with live streaming output |\n| `pull`, `push`, `tag`, `rmi` | `Containerization.ImageStore` (direct framework) |\n| `images` | Apple CLI image store (shows all pulled + built images) |\n| `stats` | VM process RSS/CPU via `ps` (VirtualMachine.xpc matching) |\n| Port mapping `-p` | Persistent `mocker __proxy` subprocess per port |\n\n## Roadmap\n\n- [x] Full Docker CLI flag compatibility (111 commands)\n- [x] Docker Compose v2 support\n- [x] Network \u0026 Volume management\n- [ ] MenuBar GUI\n- [x] Real container execution on macOS 26 (via Apple `container` CLI)\n- [x] `mocker build` — delegates to `container build` with live output\n- [x] `mocker stats` — real CPU% and memory from VM process\n- [x] Port mapping (`-p`) — userspace TCP proxy subprocess\n- [ ] Registry authentication (`mocker login`)\n- [ ] `mocker compose --scale`\n- [ ] MenuBar live container metrics (CPU, memory, logs)\n- [ ] Image layer size reporting\n- [ ] Direct Containerization framework integration (pending vminit compatibility)\n\n## Contributing\n\nContributions are welcome! Please read [docs/contributing.md](docs/contributing.md) for guidelines.\n\n```bash\n# Fork and clone\ngit clone https://github.com/yourname/mocker.git\n\n# Create a feature branch\ngit checkout -b feat/my-feature\n\n# Make changes and test\nswift test\n\n# Commit with Conventional Commits\ngit commit -m \"feat: add my feature\"\n```\n\n## License\n\nAGPL-3.0 — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt with Swift on macOS · Powered by Apple Containerization\n\u003c/div\u003e\n","funding_links":[],"categories":["Command Line Utilities","More macOS®","Developer Tools","開発ツール","Libs","Runtimes \u0026 Platforms","Container Operations"],"sub_categories":["Others","Notable Historic UNIX® and Unix®-like Operating Systems","Virtualization","仮想化","Command Line","Runtime"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fus%2Fmocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fus%2Fmocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fus%2Fmocker/lists"}