A development environment that runs as a container and is used over SSH (port 2222): a persistent per-profile home directory, a bind-mounted workspace and an in-guest rootless Docker daemon.
There are two variants. They share one image definition, one set of lifecycle commands and one host-state layout, and differ only in the runtime they drive:
| Variant | Host | Runtime | Image tag | Guide |
|---|---|---|---|---|
AppleContainer/ |
Apple-silicon macOS (Darwin arm64) | Apple Container | localhost:5000/hj/devbox-apple (tag in Common/image/tag.txt) |
README |
Docker/ |
native Linux amd64 | Rootful Docker Engine (Unix socket) | localhost:5000/hj/devbox-docker (tag in Common/image/tag.txt) |
README |
The split is deliberate: each variant builds and runs natively on its own host
(arm64 on macOS, amd64 on Linux). There is no cross-architecture build, no
automatic runtime selection. The shared requirements are in SPEC.md.
Run from the variant's directory (make -C AppleContainer build, make -C Docker build).
Config/ contains private material (SSH host key, authorized keys, root CA).
Modes (on disk authorized_keys 0400, host key 0600, the rest 0644)
and checksums are verified and enforced when the context is prepared.
A profile is an independent DevBox: its own container, its own home
directory, its own in-guest Docker state, and its own workspace mapping. The
default profile name is home.
Initializing a profile creates two persistent named volumes:
| Volume | Mounted at | Holds |
|---|---|---|
devbox-<profile> |
/home |
Your home directory and anything else installed under /home |
devbox-<profile>-docker |
/data/docker |
The in-guest Docker daemon's state (images, containers, volumes, build cache) |
./init.sh # initialize the default profile 'home'
./init.sh work # initialize a profile named 'work'
./show.sh # list all profiles: status, SSH port, workspace, mount targetshow.sh lists every initialized profile, with or without a running
container.
./run.sh /path/to/your/projectThis starts (or resumes, with -k) the profile's container with:
- the profile's
devbox-<profile>volume at/home - the profile's
devbox-<profile>-dockervolume at/data/docker - your workspace bind-mounted at
/workspace/<project-name>(the workspace directory's basename; a workspace of/mounts at/workspace/root) - the SSH port inside the container (fixed at
2222) published on an available host port --cap-add ALL, which the in-guest rootless Docker daemon and the in-container hostname setting require
Options:
-m memory-gb Memory in GB (default: 2)
-c cpu-cores CPU cores (default: one less than total host cores)
-p host-port Fixed host SSH port (default: auto-selected from 55000-59000)
-v profile-name Profile name (default: home)
-t target-path Exact in-container mount point for the workspace
(default: /workspace/<project-name>)
-k Keep the container after it stops, and resume it as-is
on the next `run.sh -k` for the same profile
The workspace argument is required, except when resuming a kept container
with -k (where it is ignored).
With the container running:
./ssh.sh # SSH in; lands in the profile's tmux session
./code.sh # open VS Code Remote-SSH against the profileBoth auto-detect the profile when exactly one is running; otherwise pass
-v <profile>.
ssh.sh lands every connection in a per-profile tmux session
(devbox-<profile>) in your workspace directory: it is created if missing,
attached if present, so reconnecting resumes exactly where you left off.
Detach with Ctrl-b d (the session keeps running) and re-run ssh.sh to
attach again. Use -s <session-name> for a named second session, one
terminal per session.
forward.sh tunnels a port from a service on localhost inside the
container to a port on your Mac, over the profile's SSH connection:
./forward.sh -p 8080 # host 8080 -> container 8080
./forward.sh -p 9090:8080 # host 9090 -> container 8080
./forward.sh -l # list active forwards
./forward.sh -D -p 8080 # close the forward on host port 8080
./forward.sh -D -y # close all forwards (with -v: just one profile)Never run forward.sh with sudo. For a privileged host port (<1024) it
prompts for sudo itself.
By default the container is removed when it stops (--rm): your volumes
persist, container-level state (e.g. running daemons you started by hand)
does not.
Run with -k to keep the container:
./run.sh -k /path/to/projectAfter the container stops, it is kept on disk with all its state. Running
./run.sh -k -v <profile> again resumes the kept container as-is, ignoring
workspace-path and -m/-c/-p/-t. To delete a kept container, use
./stop.sh -D -v <profile>.
backup.sh makes one gzip-compressed, restorable archive from a stopped
profile's /home volume. By default it also includes any Docker named
volumes stored under /data/docker/volumes, while excluding downloaded
Docker images, container layers, and build cache. Pass -f for a full
backup of /data/docker as well. The workspace bind mount and a kept
container's filesystem layer are never included.
./backup.sh work /path/to/work-backup.tar.gz
./backup.sh -f work /path/to/work-full-backup.tar.gzThe output path is explicit, must end in .tar.gz, and must not already
exist. backup.sh refuses a profile with either a normal or kept container
running, so the volume contents are consistent. It streams helper output and
reports archive progress every 5 MiB; large named-volume or full Docker
backups can take time to compress.
Restore into an absent profile only:
./restore.sh restored-work /path/to/work-backup.tar.gz
./restore.sh -y restored-work /path/to/work-backup.tar.gzrestore.sh validates the backup, and asks for a yes/no confirmation before
it creates any target volumes. Pass -y to skip that confirmation.
Discard an existing target profile deliberately before restoring it.
./stop.sh # stop the running container
./stop.sh -v <profile> # stop a specific profile's container
./stop.sh -D -v <profile> # also remove a kept container
./discard.sh <profile> # delete the profile's two volumes (asks first; -y to skip)Stopping never touches volumes. discard.sh deletes everything a profile
owns (home data and in-guest Docker state) — it is the destructive step.
On the first interactive SSH login to a profile, the image offers to install developer tools.
Each installer is idempotent. A marker (~/.devbox-install) suppresses the
prompt afterwards.
The image runs its own rootless Docker daemon (started by the in-guest
process supervisor, owned by the user). In every login shell, DOCKER_HOST
is set to the in-guest socket (unix:///run/user/1000/docker.sock).
All Docker state (images, containers, volumes, build cache) lives in the
profile's devbox-<profile>-docker volume at /data/docker.