Local Sandbox Workflow

This guide walks through creating a local sandbox, opening a shell session inside it, and archiving its contents.

Prerequisites

heyvm installed (Quickstart)
A backend configured and running

1. Create a sandbox

Use heyvm create to spin up a new sandbox:

heyvm create --name my-sandbox --type shell

The --type flag sets the sandbox environment. Options are shell, python (or py), and node (or js).

You can also specify a backend, image, and mount host directories:

heyvm create \
  --name dev-box \
  --type shell \
  --backend-type apple_container \
  --image ubuntu:24.04 \
  --mount "$HOME/projects/my-app:/workspace"

Useful create options

Flag	Description
`--name <name>`	Sandbox name (required)
`--type <type>`	Environment type: `shell`, `python`, `node`
`--backend-type <backend>`	Execution backend (e.g. `msb`, `bubblewrap`, `apple_container`)
`--image <image>`	Container/VM image
`--mount <host:sandbox>`	Mount a host directory (repeatable)
`--env <KEY=VALUE>`	Set environment variables (repeatable)
`--start-command <cmd>`	Command to run on startup
`--setup-hook <cmd>`	Shell command to execute after creation (repeatable)

2. Open a shell session

Once your sandbox is running, drop into an interactive shell with heyvm sh:

heyvm sh my-sandbox

You can pass either the sandbox name (slug) or its ID. This gives you a full interactive terminal inside the sandbox where you can install packages, edit files, run processes, and so on.

$ heyvm sh my-sandbox
root@my-sandbox:/# whoami
root
root@my-sandbox:/# ls /workspace
my-app/

To run a single command without an interactive session, use heyvm exec instead:

heyvm exec my-sandbox -- ls /workspace

3. Create an archive

Archives capture the filesystem state of a sandbox so you can redeploy or share it later.

Archive from a running sandbox

To archive the mounted contents of a sandbox:

heyvm archive my-sandbox

You can give the archive a name for easier identification:

heyvm archive my-sandbox --name "baseline-setup"

On success you'll see output like:

Archive created successfully:
  ID: abc123
  Size: 15728640
  Created: 2026-03-22T10:00:00Z

Archive a local directory

If you want to archive files from your host machine directly (without a running sandbox), use archive-dir:

heyvm archive-dir /path/to/my-project --name "my-project-v1"

By default this archives relative to a /workspace mount path. You can change it:

heyvm archive-dir . --mount-path /app

Build artifacts like node_modules, target, and dist are excluded by default. To include everything:

heyvm archive-dir . --no-ignore

Putting it all together

A typical workflow looks like this:

# Create a sandbox with your project mounted
heyvm create --name my-app --type node --mount "$PWD:/workspace"

# Shell in and set things up
heyvm sh my-app
# ... install deps, configure the environment, etc.

# Archive the result
heyvm archive my-app --name "my-app-configured"

The archive ID can then be used with heyvm deploy to launch a production sandbox from that snapshot. See the CLI reference for the full list of commands.