Run a sandbox locally

The Quave ONE CLI can run a sandbox on your own Linux machine. Use it to give a person or a coding agent a locked-down Linux environment for one project, without a Quave ONE account and without touching the rest of the machine.

A local sandbox is a separate thing from the managed sandboxes in the rest of this section. It has its own commands and does not use templates, revisions, or the Public API.

	Local sandbox	Managed sandbox
Runs on	Your Linux machine, with Docker Engine	Quave ONE infrastructure or your own nodes
Driven by	quaveone sandbox commands	Public API, MCP server, dashboard
Quave ONE account	Not needed	Needed
Isolation	Container (runc), or gVisor if you install it	gVisor
Files	A folder on your machine, backed by a local bucket or your own S3 bucket	Persistence modes

Requirements

• Linux with Docker Engine and the Compose v2 plugin.
• /dev/fuse on the host.
• The sandbox directory on a shared mount, the default on systemd distributions.
• Outbound HTTPS to github.com, raw.githubusercontent.com, Docker Hub, and hub.volobj.quave.one.

macOS, Windows, Docker Desktop, rootless Docker, and Podman are not supported as the local host. On those, run the sandbox on a Linux server or VM you reach over SSH. See Run it on another Linux server.

Install and check your machine

The sandbox command needs CLI v1.1.0 or later. The installer gets the latest release.

curl -fsSL https://raw.githubusercontent.com/quaveone/cli/main/install.sh | bash
quaveone sandbox doctor

doctor prints one line per check and a verdict, and tells you what to fix. A warning about gVisor is fine: it is optional.

Create your first sandbox

quaveone sandbox up --name my-project
quaveone sandbox status --name my-project
quaveone sandbox shell --name my-project

The first up downloads about 214 MB of images and takes around 35 seconds. After that it takes about 10 seconds. status should show Hub: connected (event mode).

Add --name to every command. Without it, commands use a sandbox called default. Each name is a separate sandbox, so one per project keeps projects apart. quaveone sandbox list shows them all.

Run a single command without opening a shell:

quaveone sandbox exec --name my-project -- sh -c 'echo hello > /workspace/persist/hello.txt'
ls ~/quaveone-sandboxes/my-project/data

What the sandbox can reach

• It runs with no capabilities, a read-only root filesystem, and your host user's uid and gid.
• It sees no host files except its own workspace, and holds no volume key or storage credential.
• Outbound internet access is open, so a process inside can download packages and call APIs.
• There is no Docker socket or docker command inside. Tools that need Docker, such as docker compose, do not work from inside the sandbox. Run those services outside it.

To add gVisor as a stronger boundary, install it and pass --runtime runsc to up.

Which files persist

Path in the sandbox	Survives
/workspace/persist	Everything. It is also ~/quaveone-sandboxes/<name>/data on the host, owned by your user
The rest of /workspace	pause and resume only
$HOME and /tmp	Nothing. They are lost with the container

Keep your project in /workspace/persist. While the sandbox is paused or down, the host folder is empty. Resume the sandbox to get the files back.

Every file in /workspace/persist is uploaded to the volume when it is closed, so do not keep these there: SQLite or other single-file databases, lock files, sockets, node_modules, .venv, build output, continuously appended logs, or secrets. Keep dependencies and build output elsewhere in /workspace. Hard links are not supported.

Pause, resume, and stop

quaveone sandbox pause --name my-project    # saves /workspace and stops the sandbox
quaveone sandbox resume --name my-project   # starts it and restores the snapshot
quaveone sandbox down --name my-project     # stops it without a snapshot
quaveone sandbox up --name my-project       # starts it again after down

pause skips node_modules, .venv, and .cache unless you change the list with --exclude. down without pause loses everything outside /workspace/persist.

With the default local storage, quaveone sandbox down --purge deletes the sandbox and its data for good.

Back up the volume key

Each workspace has a volume key, and this machine holds the only copy. Back it up right after creating the sandbox:

quaveone sandbox key backup --name my-project

This writes ~/quaveone-sandbox-my-project.key-backup and prints its path. Move the file to a password manager and delete it. Without the key, nobody can recover the workspace or join it from another machine.

Check that it works

quaveone sandbox verify --name my-project

verify tests the sandbox's guarantees in about 25 seconds and ends with a summary such as 17 passed, 1 skipped, 0 failed. If a line says FAIL, check quaveone sandbox logs --name my-project.

Add your own tools

The root filesystem is read-only, and programs under /workspace cannot be executed directly: they fail with Permission denied. Put the tools you need in an image built on the sandbox base image.

For example, an image with the Claude Code CLI:

FROM quaveone/sandbox-base:0.5.5
USER root
RUN npm install -g @anthropic-ai/claude-code
USER 1000

Build it and pass it to the first up:

docker build -t my-sandbox .
quaveone sandbox up --name my-project --image my-sandbox

quaveone sandbox images prints the default images and their versions. Because $HOME does not survive the container, a tool that stores its login there asks for it again after a restart.

Share a workspace or keep it off this machine

By default the data lives in a local MinIO container on this machine. To share the workspace between machines or keep it safe if the machine is lost, create the sandbox on an S3-compatible bucket you control. The bucket must already exist:

export QUAVEONE_SANDBOX_S3_ACCESS_KEY=...
export QUAVEONE_SANDBOX_S3_SECRET_KEY=...
quaveone sandbox up --name my-project --s3-endpoint https://s3.example.com --s3-region us-east-1 --bucket sandboxes

The endpoint, bucket, and key cannot change later, and a sandbox on local MinIO cannot be moved to a bucket. Create a new one with another --name instead.

Machines that share a volume learn about each other's changes through the public event hub at wss://hub.volobj.quave.one. The hub sees file paths and sizes, never file contents or keys. See its privacy page. up connects to it by default. Pass --local-hub to run without internet access to the hub.

Run it on another Linux server

From any machine with the docker CLI and the Compose v2 plugin, including macOS, you can run the sandbox on a Linux server you reach over SSH. Your settings and keys stay on your machine.

quaveone sandbox doctor --remote my-server
quaveone sandbox up --name my-project --remote my-server
quaveone sandbox shell --name my-project

ssh my-server true must work without a prompt, and the SSH user needs access to Docker on the server. Set --remote on the first run: it cannot change later.

Let an agent set it up

An AI coding agent can do all of this from one URL. Tell it:

Read https://hub.volobj.quave.one/llms.txt and give me a sandbox; run verify at the end.

That file is also the full reference for every option, error message, and multi-machine flow.