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.
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.