Boxge brings a Compose-style workflow to Apple's native container runtime on macOS: file-based
stacks, a config editor, live logs, and a web terminal. It also has a menu bar app, and a command
line tool and MCP server so coding agents can manage stacks.
It is a fork of Dockge (MIT, © Louis Lam). Boxge keeps
Dockge's architecture (a TypeScript backend, a Socket.IO real-time layer, and a Vue 3 frontend) and
replaces the one part that shelled out to docker compose with an adapter that drives the
container CLI directly. Apple's runtime has no Compose primitive, so Boxge implements that layer
itself: it parses a compose.yaml, turns each service into a container run, and manages the
networks of each stack.
- macOS 26 or later, on Apple silicon.
- Apple's
containerruntime, version 1.7.1 or later. - Node 22 or later.
Boxge runs as a native host process and calls the container CLI. It is not itself a container, and
there is no Docker socket to mount.
npm install
npm run build:frontend
npm start # http://localhost:5001Boxge starts the container runtime on boot if it is not already running.
Open the web UI and create an administrator account on first launch. Stacks live at
~/.boxge/stacks/<name>/compose.yaml. To run Boxge as a service that starts at login, see
docs/running-on-macos.md.
Every interaction with the runtime lives in one module, backend/container/. It reads a stack's
compose.yaml, turns each service into a container run, and handles the things the runtime does
not do on its own:
depends_onordering, with health gating.- Health checks, run with
container exec. - Restart policies, with a growing delay between attempts and a limit for
on-failure:N. A service you stopped stays stopped, also across a Boxge restart. - Cleanup of anonymous volumes and of the stack's networks on
down.
A deploy only recreates the services whose configuration or image changed. Live logs keep following
a service after it is recreated. Boxge checks the container version at boot and warns when it is
older than the minimum.
Variables (${VAR}, ${VAR:-default}, $$ for a literal $) are filled in from the stack's
.env and from global.env in the stacks directory, the same way Compose does it.
Supported service keys include image, build (with args and target), command,
entrypoint, environment, env_file (with required: false), ports (short and long form,
host IP, ranges), volumes (short and long form), tmpfs, networks, secrets, depends_on,
healthcheck, restart, profiles, extends (same file or another file), pull_policy,
stop_grace_period, stop_signal, user, working_dir, labels, cpus, mem_limit,
cap_add, cap_drop, read_only, init, tty, ulimits, platform and the dns options.
Things that work differently from Docker, because of the runtime:
- Only folders can be mounted, not single files. A bind mount of a file such as
./nginx.conf:/etc/nginx/nginx.confis refused with a message; mount the folder that holds it. For the same reasonconfigsis not supported. - Secrets are mounted read-only in
/run/secrets, from afileor anenvironmentvariable. Other target paths are not supported. - Named volumes keep the name you give them. A volume called
datais shared by every stack that uses that name. Give it aname:under top-levelvolumesto choose a distinct one. Volumes markedexternalare never created or removed. - Networks: each stack gets
boxge-<stack>, and every other network it declares becomesboxge-<stack>.<name>, unless it isexternalor has its ownname:.internal: trueis honoured. Per-network aliases and fixed addresses are not. on-failurerestarts after any exit andservice_completed_successfullycannot check the exit status, because the runtime does not report exit codes.- A service without a host port in
portsis published on the same port number.
Anything Boxge does not support, for example container_name, hostname, privileged,
network_mode or links, is listed as a warning on the stack page and in the deploy output
instead of being dropped silently.
Published ports (ports: in Compose) are bound on the host, so a service is reachable at the
machine's address on its published port, for example http://<your-mac-ip>:8080. A port written as
127.0.0.1:8080:80 stays on loopback. The UI links to the published address, using the host's LAN
IP by default. Each container also has a private IP on its network, shown for reference; that one
only works from the Mac itself.
Services can also reach each other by name. This is off by default. To turn it on, register a DNS domain with macOS once, as an administrator:
sudo container system dns create boxge.testThen enter the same domain under Settings, General, "Service DNS domain", and redeploy your stacks.
Inside a stack, a service named db is then reachable as db. From the Mac, and from other stacks,
it is db.<stack>.boxge.test. Boxge does this with the runtime's DNS aliases and a search domain per
stack, and it does not edit the runtime's own configuration.
extra/menubar/ has a native macOS menu bar app. It shows your stacks with their state, starts,
stops and restarts them, opens a stack in the web UI, stops all containers at once, and starts or
stops Apple's container runtime:
./extra/menubar/build.sh --installSee its README for how it talks to the server.
Coding agents such as Claude Code, Codex, pi and omp can manage stacks through an MCP server or a command line tool, both in this repo:
bin/boxge mcp-config # how to register the MCP server with each agent
bin/boxge help # the command line toolThey can read status, logs and disk usage, dry-run a compose file, create, edit, deploy and delete
stacks, run a command in a container, and change settings. See
extra/agent/README.md for the tool list, the safeguards and the
underlying API.
| Variable | Default | Description |
|---|---|---|
BOXGE_PORT |
5001 |
Port the web UI listens on. |
BOXGE_HOSTNAME |
all interfaces | Address to bind the server to. |
STACKS_DIR |
~/.boxge/stacks |
Where stacks are stored. |
BOXGE_DATA_DIR |
./data/ |
Application data (database, settings). |
BOXGE_ENABLE_CONSOLE |
false |
Enable the host command console. |
BOXGE_SKIP_RUNTIME_START |
unset | Set to 1 to stop Boxge from starting the container runtime on boot. |
BOXGE_LOCAL_API_FILE |
~/.boxge/local-api.json |
Where the server publishes its local API address and token. |
BOXGE_CONTAINER_BIN |
container |
Path to the container command, if it is not on the PATH. |
The legacy DOCKGE_* equivalents still work.
npm install
npm run dev # backend (5001) and frontend (5000) with hot reload
npm run check-ts # type check
npm run lint # ESLintWhat the runtime actually does (JSON output, networking, DNS) was first written up in
docs/phase0-spike.md, which carries a note on what has changed since.
Open an issue on GitHub.
If something is broken, include:
- what you were doing
- what you expected
- what actually happened
- your macOS version and the output of
container --version - any error output from the terminal, or
data/boxge.err.logif you run it as a service
If you want a feature, describe the problem you are trying to solve, not just the feature you have in mind. Knowing the goal makes it much easier to help.
This is a side project with a single maintainer, so a reply might take a while. Pull requests are welcome, smaller and focused ones most of all.
MIT. Boxge is a fork of Dockge by Louis Lam; the original copyright and license are kept in
LICENSE. Not affiliated with or endorsed by Apple.