Guides / Your first sandbox
Your first sandbox
A sandbox is a whole separate computer running on your Mac — its own kernel, its own container engine, its own network. This walkthrough takes about five minutes.
Make one
$ kosa8 sandbox create web --memory 2048 sandbox web ready in 640ms
Under a second for a machine with its own operating system. That speed is the reason throwing one away and making another is a reasonable thing to do.
Put an image in it
Each sandbox has its own private image store. Nothing is shared with your host, so an image pulled here cannot affect anything outside.
$ kosa8 sandbox pull web alpine:3.20
pulled docker.io/library/alpine:3.20 into web
Run something in it
$ kosa8 sandbox run web alpine:3.20 sh -c "hostname" kosa8-guest
A different computer name, because it really is a different computer.
See what you have
$ kosa8 sandbox ls
SANDBOX STATE CPUS MEMORY PARENT
web running 2 2048MiB -
The PARENT column matters later: when you copy a machine, the copies remember where they came from.
Decide what it can reach
A sandbox with no limits is just a slower container. The point is deciding, up front, what it can see and where it can connect.
# only these two hosts, nothing else $ kosa8 sandbox create build --egress allow:registry.npmjs.org,github.com # no network at all $ kosa8 sandbox create offline --egress deny # show it one folder, read-only $ kosa8 sandbox create review --mount ~/code/api:/work:ro
The limits are applied by the machine itself. Something inside that tries to reach a host you did not allow gets a failed connection — there is nothing for it to talk its way around.
How much room it has
$ kosa8 sandbox create web --disk 500 sandbox web ready in 658ms (500 GB disk)
A sandbox's images, layers and files live on their own disk, separate from the guest root image — so a guest rebuild never touches them, and the size is declared rather than paid for. The image is sparse: a 1 TB sandbox occupies about 22 MB until something is written to it, and forking one stays as fast as forking a small one.
The ceiling comes from your plan, and capacity above it is its own add-on — 500 GB at $100/mo,
1 TB at $200/mo. The disk is your own SSD; what the add-on covers is kosa8 snapshotting, forking
and pushing a sandbox that size. kosa8 license status shows what yours allows.
Stopping without losing it
$ kosa8 sandbox down web stopped web (start it again with `kosa8 sandbox up web`) $ kosa8 sandbox up web sandbox web ready in 594ms
A stopped sandbox keeps its own disk, so it comes back with everything in it — packages installed, images pulled, files written. The guest's filesystems are flushed before the machine goes away, which is what makes that safe rather than merely likely.
The same is true of a daemon restart. A sandbox's VM cannot outlive kosa8d, so
after kosa8 daemon start your sandboxes are listed as stopped and
sandbox up boots them again. What does not come back is running processes: for that,
take a snapshot first — resuming mid-process is what a snapshot is
for.
Clean up
$ kosa8 sandbox rm web
removed web
If the sandbox had checkpoints, they go with it, and so do the snapshots behind them. Leaving them would mean a future sandbox that reused the name could rewind into a stranger's machine.
Save and undo — the part no other container tool does.