bhatti create

Create a new sandbox VM. Each sandbox is an isolated Linux environment with its own kernel, filesystem, and network interface — created in seconds, paused for free, resumed in microseconds.

Synopsis

bhatti create [flags]

Description

Boots a krucible microVM and registers it under the authenticated user. Returns once the guest agent is responding.

The created sandbox is in the running (hot) thermal state. Without --keep-hot, it pauses to warm after 30 seconds of inactivity and freezes to cold (memory snapshotted to disk, RAM freed) after 30 minutes. Any incoming request transparently wakes it.

--volume and --secret reference resources that must already exist (create them with bhatti volume create and bhatti secret set). --file reads a local file at submit time and writes its bytes to the guest path during boot — convenient for injecting config files without a volume.

When used with --template, request-side --secret and --file are merged into the template's defaults: secrets from both lists are resolved (request-side names that don't exist in your secret store return 400); --file adds to the template (templates have no files of their own). For environment variables, --secret wins over --env for the same name.

--cpus accepts fractional values (e.g. 0.5, 1.5); the host scheduler runs vCPUs as time-shared threads, so fractional allocation maps to "you're entitled to ~N vCPU-seconds per second."

--hugepages uses 2MB hugepages for the VM's memory, which makes boot faster. Use it for short-lived sandboxes, not for long-lived agents.

The --memory server default is 1024 MB. The --cpus default is 1. Both are capped by the user's per-sandbox limits set via bhatti user create.

Examples

# Smallest possible sandbox
bhatti create --name dev

# Custom resources, env vars, and an init script
bhatti create --name api \
  --cpus 2 --memory 2048 \
  --env NODE_ENV=production,LOG_LEVEL=info \
  --init "cd /workspace && npm install"

# Mount a persistent volume; create the volume first
bhatti volume create --name workspace --size 5120
bhatti create --name dev --volume workspace:/workspace

# Reference a stored secret as a guest env var
bhatti secret set OPENAI_KEY sk-...
bhatti create --name agent --secret OPENAI_KEY

# Inject a local config file at boot
bhatti create --name worker --file ./config.json:/etc/worker/config.json

# Use a non-default rootfs image (browser tier with Chromium + Playwright)
bhatti create --name scraper --image browser

# Autonomous agent — never paused, even when idle
bhatti create --name agent --init "hermes gateway" --keep-hot

Options

| Flag | Default | Description | | ---- | ------- | ----------- | | --name <string> | auto-generated | Sandbox name. Must match [a-zA-Z0-9][a-zA-Z0-9._-]{0,62}. | | --cpus <float> | 1 | Number of vCPUs. Fractional values allowed (e.g. 0.5). Capped by per-sandbox limit. | | --memory <int> | 0 (server uses 1024) | Memory in MB. 0 means use the server default. Capped by per-sandbox limit. | | --disk-size <int> | 0 (use image size) | Rootfs disk size in MB. 0 means inherit from the base image. | | --env <K=V,K=V> | — | Environment variables, comma-separated, applied to every command. | | --init <string> | — | Init script that runs at boot as an attachable session named init. Survives the boot path; visible in bhatti ps. | | --keep-hot | false | Disable thermal transitions. Use for sandboxes that maintain external connections (websockets, polling agents). | | --hugepages | false | Use 2MB hugepages. Faster boot. | | --template <name> | — | Create from a template. Template fields are defaults; flags here override them. | | --image <name> | — | Rootfs image. Built-in: minimal, browser, docker, computer. Or a name from bhatti image list. | | --volume <spec> | — | Attach a persistent volume. Format: name:mount[:ro]. Repeatable. | | --secret <name> | — | Reference a stored secret by name. Decrypted and exposed as an env var. Repeatable. | | --file <local:guest> | — | Read a local file and write it to guest inside the sandbox at boot. Repeatable. |

See Global flags for --url, --token, --json, --timing, --data-dir.

Output

Default output is a verbose summary:

sandbox/dev created (1 vCPU, 1024 MB)
  Shell: bhatti shell dev

With --json, the full sandbox object is printed.

If a sandbox with the requested name already exists and is identical, the server returns the existing record and the CLI prints:

sandbox/dev unchanged (already exists)

This makes create safe to re-run from scripts.

Exit codes

| Code | Meaning | | ---- | ------- | | 0 | Sandbox created, or already existed with the same configuration. | | 1 | Validation error, quota exceeded (e.g. max-sandboxes reached), name conflict, or boot failure. |