napbox
Health Warn
- License — License: NOASSERTION
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Warn
- process.env — Environment variable access in examples/demo/api/server.js
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Per-worktree dev environments for coding agents on Apple silicon Macs: your existing compose.yaml, no Docker, no port clashes, idle environments sleep and give their memory back.
napbox
Local dev environments for coding agents on Apple silicon Macs, without Docker.
napbox reads a project's compose file and gives every git worktree its own isolated set of services (databases, object storage, backends). Host ports are assigned by napbox and stay fixed for that environment. Idle environments go to sleep and wake up on the next connection. Agents drive it through MCP tools; scripts use the napbox command.
It is built on Apple's open-source Containerization framework: one lightweight Linux VM per environment, with all its services in it.
Status: 0.1.8, early. Used daily on one machine for several projects (PostgreSQL with PostGIS, Redis, MinIO, Go and Node backends, nginx front ends). Expect rough edges.
Why
Run a few coding agents in parallel, each in its own worktree, with Docker compose, and you hit three things:
- Port clashes. compose files hardcode host ports, so the second worktree's
upfails on 5432. If they share one database instead, one agent's migration breaks another's data. - Memory that never comes back. While any container is running, the Docker Desktop VM keeps all the memory you gave it, and agents rarely stop what they started.
- Agents fumbling with Docker. They assemble
docker composecommands, guess ports and leave containers behind.
With napbox, each worktree gets its own services from the same compose file, on ports that never clash and stay fixed until you down it. Idle environments sleep and give their memory back; the next connection wakes them, and a database is usually ready in about a second. A new worktree can start with a copy of main's data. Agents use MCP tools and get JSON back.
To see it in a couple of minutes, try the demo project.
Requirements
- macOS 26 or later, Apple silicon
- Node.js 22.22 or later
- Claude Code for the plugin, or Codex for the MCP tools (the
napboxcommand works without either)
Install
In Claude Code:
/plugin marketplace add coffeecoproject/napbox
/plugin install napbox@napbox
The first time an agent needs services, napbox reports that it is not set up and the agent calls the setup tool (Claude Code asks you first). Setup:
- downloads the Kata Containers kernel package from GitHub (about 700 MB, checked against a fixed checksum) and runc (about 10 MB), and pulls the vminit image from ghcr.io;
- asks macOS to install Rosetta if it is missing (for x86 programs inside the VM);
- copies
napboxdto~/Library/Application Support/napbox/and registers it as a login item (~/Library/LaunchAgents/io.github.coffeecoproject.napbox.plist).
In Codex:
npx napbox setup codex
This runs the same setup and adds napbox's MCP tools to Codex (with codex mcp add). Codex gets the tools only: the skill and the hooks (telling the agent its ports when a session starts, stopping docker compose up) are part of the Claude Code plugin.
Without an agent: npx napbox setup.
How it works
- One environment per worktree. Environments are named
<project>/<worktree>(the main checkout is<project>/main). Two worktrees of the same project run side by side without port clashes. - Ports. In compose, write only the container port (
- "5432"). napbox assigns a host port on127.0.0.1and keeps it for the environment across sleep, wake,upagain, napboxd restarts and profile changes. It is released only ondown. Other worktrees and temporary environments get other ports, so read them fromnapbox envinstead of hard-coding them. When a service needs its own address on the host (for example to build links a browser opens), write${NAPBOX_API_3100}inenvironmentorenv_file; napbox replaces it with the address this environment was given (127.0.0.1:41217) when the service starts. - Ports for processes on the Mac. When the project's own programs that run on the Mac (a dev backend, the backend and web pages that end-to-end tests start) also need their own ports per worktree, add
x-napbox: {host_ports: [server, web]}at the top level of compose. Each name gets one port, exposed asNAPBOX_HOST_SERVER=41230(just the port number), and it stays fixed untildownlike service ports. napbox does not hold these ports; the project's programs listen on them. napbox checks a port is free when it assigns it; if another program takes it later, the project's program fails to start with "address in use". Names use lowercase letters, digits and underscores, start with a letter, and must not end in_<digits>. - Data from the main checkout. Add
x-napbox: {seed: [pgdata, s3data]}at the top level of compose to give a new worktree the main checkout's data (accounts, uploaded files) instead of empty volumes. Each time a worktree's environment stops cleanly (idle sleep,napbox sleep, napboxd quitting), napbox keeps an APFS clone of those volumes as its snapshot; the firstupin a new worktree copies the main checkout's latest snapshot, without stopping or pausing it. It takes milliseconds and no extra disk space until either side writes. If the main checkout has no snapshot yet,upfails withsnapshot_not_foundrather than starting with empty volumes. A stop only counts as clean when every service exits within itsstop_grace_period(10 seconds unless set) and the disk sync succeeds; otherwise no snapshot is taken, andstatusshows why undersnapshotError(thesnapshot_not_foundmessage repeats it). For a service that is slow to stop, first check its log for what it waits on (some waits can be turned off); give it a longerstop_grace_periodonly for the time it really needs. One-off services such as migrations run again on the copied data. - Sleep. After 30 minutes without connections an environment sleeps and its memory goes back to macOS. The next connection to one of its ports wakes it; that connection waits only until the service it connects to (and the services that one depends on) is ready, usually about a second for a database, while the rest of the environment keeps starting. Services start one by one in dependency order, so a service later in that order also waits for the ones before it to start. If any of those services has a
develop.watchsync rule, the connection waits for the whole environment, so files changed while it slept are already synced. - Temporary environments.
napbox up --temp <name>starts a throwaway environment next to the dev one (an empty test database, for example), andnapbox down --temp <name>deletes it.napbox run <service>starts a one-off environment, runs one service in the foreground and returns its exit code. - Builds.
build:is built inside a dedicated VM with BuildKit; the build cache is shared by all environments. - Network. Environments cannot reach the host or the local network.
napbox egress nonealso cuts off the internet, leaving only the services in the same environment. - Environments owned by another program. A program that runs coding agents on copies of a project (CodeOS, for example) can create environments itself with the TypeScript client:
new NapboxClient().create({ name: "codeos/goal-12", owner: "codeos", directory: "/path/to/copy" }). Passconfine: truewhen the agent can edit that copy's compose and must not see anything else on the Mac: every host path napbox would read or mount (compose files,.env,.napbox.yaml,env_file, bind mounts,secretsfiles, the buildcontextand Dockerfile,.dockerignore,develop.watchpaths) must resolve, following symlinks, to a path insidedirectory, orcreatefails withpath_outside_directoryand nothing starts. napbox records the copy's real path and checks again before every build and start (wake,reset, restarts,develop.watchrebuilds), so replacing a folder, or the copy directory itself, with a symlink afterwards stops the environment from starting. The VM only gets the copy itself, so a symlink swapped in after the check resolves inside the VM, not on the Mac. The program owning the environment must keep the agent from deleting or recreating the copy directory itself, since a swap timed between the last check and the VM opening the directory cannot be caught. Results carryconfined: true. The client checks that napboxd is 0.1.7 or newer before sendingconfine, because older versions ignore it and start the environment unrestricted.
Commands
All commands print JSON (napbox status --text prints a table).
| Command | What it does |
|---|---|
napbox up [-f compose] [--build] [--profile P] |
Create or wake the environment, wait until healthy, print ports and variables |
napbox env |
Print export NAPBOX_<SERVICE>_<PORT>=127.0.0.1:<port> lines, ready for eval "$(napbox env)" |
napbox status [--text] |
State and ports of napboxd and the environments |
napbox logs <service> [--tail N] [-f] |
Service logs, without waking the environment |
napbox exec <service> -- <command> |
Run a command in a service (not interactive) |
napbox run <service> [-- <command>] |
Run one service once in a throwaway environment |
napbox reset <volume...> [--from <dir>] |
Empty named volumes, or with --from replace them with the latest snapshot of another worktree's environment of the same project (the old data is kept for 7 days) |
napbox sleep / napbox down |
Sleep now / remove the environment (data kept for 7 days) |
napbox egress <open|none> |
Switch network access |
--temp <name> works with up, env, logs, exec, egress and down.
Compose support
napbox supports what local dev compose files commonly use, and rejects everything else with an error that says what and why, instead of ignoring it.
Supported: image, build (context, dockerfile, target, args), command, entrypoint, environment, env_file, working_dir, init, shm_size, tmpfs, pull_policy, stop_grace_period, ports (container port only), expose, volumes (named volumes, directories and single files), depends_on with conditions, healthcheck, restart, profiles, develop.watch, secrets (file form), memory limits (mem_limit, deploy.resources.limits.memory; as in Docker, a service without one is not capped on its own and shares the whole environment's memory), the default network, variable substitution, multiple compose files and YAML merge keys.
Not supported, among others: read_only, cpus, pids_limit, security_opt, platform, privileged, cap_add: NET_ADMIN, network_mode, configs, the !reset and !override YAML tags, and build options beyond the four above.
Differences from Docker
- A single service cannot be restarted on its own. When a service restarts under its
restartpolicy, the whole environment restarts. Put setup work (create databases, run migrations) in one-shot services that the backend waits for withcondition: service_completed_successfully. - Environments cannot reach each other. Services inside one environment can, by service name.
- Several networks are merged into one: all services of an environment can reach each other, and
internal: trueon a network has no effect. To cut off the internet, usenapbox egress nonefor the whole environment. napbox rungives the service its host ports, unlikedocker compose run.exechas no interactive terminal.- Builds cannot use your Docker login or local Docker images:
FROMmust be pullable from a public registry. - napbox does not export images. Package release images with another tool, such as Apple's
container. - Memory is returned to macOS only when an environment sleeps.
- There is no swap in the virtual machine. When a service stalls on memory (at its own limit, or with the whole environment's memory used up), napbox ends the process using the most memory and says why in the service's log, instead of letting it hang.
Contributing
Bug reports and ideas are welcome as issues.
Code contributions will require signing a Contributor License Agreement (CLA). You keep the copyright to your contribution; the CLA lets coffeecoproject license it under the project's current license and under other terms in the future, including commercial ones. The CLA is not in place yet, so pull requests are not accepted for now. Please open an issue instead.
License
Functional Source License 1.1, ALv2 Future License (FSL-1.1-ALv2). You can use, modify and redistribute napbox for any purpose, including using it at work on commercial projects, except making it available to others in a commercial product or service that substitutes for napbox or offers substantially similar functionality. Each version also becomes available under the Apache License 2.0 two years after it is released.
Versions 0.1.7 and earlier were released under the Apache License 2.0 and remain under it.
The npm package bundles third-party code; see NOTICE.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found