---
name: modal-sandboxes
description: Connect Modal and create reusable cloud machines with the bundled standard image, on-demand daemon installation, and snapshot lifecycle.
---

# Modal machines

1. Install `builtin:environment-modal-sandbox` and configure `tokenId` and
   `tokenSecret` in plugin Settings. Do not print credentials. `appName` defaults
   to `bb-sandboxes`. The plugin page defines named sandbox size presets and
   images; the initial Default image contains the bundled Dockerfile.
2. Run `bb modal account inspect --json` to test the connection without allocating
   compute. Exit status 1 means configuration or connection failed; the JSON gives
   a secret-free message. SDK callers use the plugin's `modalRpcContract`
   (`account.inspect`) through `sdk.plugins.callRpc`.
3. Resolve the project with `bb project list --json`. It needs a Git remote,
   credentials to clone it, and machine server access reachable from Modal.
4. Create a standalone machine with
   `bb machine create --provider modal-sandbox --json`.
   SDK: `hosts.experimental_create({machineProviderId:"modal-sandbox",key})`.
   Standalone machines remain until explicitly removed. Sandboxes created with
   a thread retire after their last live thread is archived.
   Use a stable creation key for retries. Composed thread creation accepts
   optional configured names as `{"preset":"Large","image":"Node 22"}`.

Settings edits the Default image's Dockerfile, adds named Dockerfile or Modal
image-ID entries, and adds named CPU/memory presets. Without a preset, new
machines reserve 1 CPU and 2 GiB; Modal lets a sandbox burst above its
reservation and bills whichever is higher. One or zero choices use the
default without adding a composer chip; multiple choices share one chip. Agents
can run
`bb modal image show > Dockerfile`, edit the file, then run `bb modal image set
--file ./Dockerfile`. `bb modal image reset` restores the bundled default.
Append `--json` for structured output. File paths resolve from the CLI directory
on the current thread's host, or the server machine without thread context.
Typed RPCs `image.definition`, `image.set({dockerfile})`, and `image.reset`
return `{dockerfile, customized}` through `sdk.plugins.callRpc`.

Only one FROM followed by RUN, ENV, WORKDIR, and USER is supported. Comments and
line breaks are preserved; no COPY, ADD, uploaded context, or multi-stage builds.
Maximum length is 65,536 characters. Failed validation leaves the saved definition
unchanged. Save/reset is plugin-wide and affects new machines only; it does not
allocate resources or build. The next launch builds/reuses the content-hashed
image. The bundled default supplies tools, not the BB daemon.
Core installs the matching daemon during initial bootstrap, then handles
machine enrollment, connection and checkout cloning. Creation progress
reports build/allocation/bootstrap failures. Cancelling a launch prevents subsequent
sandbox allocation, but an already submitted shared image build may finish.

Project dependencies and services belong in `.bb-env-setup.sh`. Core runs it after
creating the checkout. Restoring a machine does not rerun setup. Core also owns
`.bb-env-teardown.sh` for owned environments. Attached user-maintained paths skip
both hooks. Configure runtime secrets through core Machine environment settings;
never bake them into the image. There are no user recipes, context uploads, smoke
verification records or promotion commands.

Use `bb machine list --json` for core suspension state and
`bb modal machine inspect HOST_ID --json` for Modal expiry and saved-image
status. Idle pause defaults to 15 minutes; compute lifetime is fixed at Modal's
24-hour maximum. There is no retention/keep policy; remove machines explicitly.

Manual and idle pauses drain BB work, stop the daemon, snapshot the filesystem,
and durably record the snapshot before terminating compute. Resume restores the
saved filesystem without rerunning setup. Core defers idle pause while persisted state
ties a starting thread launch or provisioning environment to the machine, or while project
checkout setup is pending; the next scheduled sweep retries. Continue interrupted turns
explicitly.

There is no pre-expiry scheduler. If a sandbox runs for its full 24-hour
lifetime, changes since the last successful pause may be lost.
Pause before the timeout to save work. Failed saves retain compute while it exists.
Missing compute never silently restores an older snapshot; a checkpoint from an
interrupted planned suspension remains recoverable.

Remove with `bb machine remove MACHINE --yes --json`. This removes
owned environments, compute and private snapshots. Shared standard images remain
cached for future launches. Builds and machines incur Modal usage; obtain task
authorization before allocating them during testing.

## Debug an image

```sh
bb modal image build --json
bb modal sandbox run --json
bb modal sandbox exec SANDBOX -- bash -lc 'node --version && which git'
bb modal sandbox exec SANDBOX --json -- bash -lc 'exit 7'
bb modal sandbox stop SANDBOX --json
```

`bb modal --help` and `bb modal <command> --help` list the commands, arguments,
and options and exit 0. `--json` is accepted anywhere before `--`; with it, a
failure is also reported as `{"ok":false,"error":{code,message,hint?}}` on
stdout. Everything after `--` belongs to `sandbox exec` and is never parsed as
an option.

Build uses the saved Dockerfile and the same account-wide image cache as machine
creation. It returns the image ID and the final 65,536 characters of build logs
when finished; failures include captured logs and the vendor error. Build logs
are collected through Modal 0.10's gRPC middleware because its image builder does
not forward them. This adapter is tied to the pinned vendor SDK. Output is not
streamed to the CLI. An already submitted build can finish after CLI cancellation.

Run builds or reuses that image and returns `sandboxId`, `imageId`, `expiresAt`
and build `logs`. Debug sandboxes expire after 30 minutes, use Modal's default CPU
and memory, and contain no injected BB credentials, daemon, project clone or setup
hook. They are separate from BB Machines and do not snapshot. Files and running
processes remain between exec calls until stop or expiry. Copy successful fixes
into the Dockerfile, save it, and run a new sandbox to verify them.

Exec passes arguments after `--` literally. Use `bash -lc` for shell expressions.
Place BB's `--json` before `--`; command flags after it belong to the command.
Commands have a 60-second timeout and output is capped at 128 KiB per stream with
a truncation marker. Plain output preserves stdout/stderr and the command exit
code; JSON returns `{exitCode,stdout,stderr}` with the same CLI exit status.
Stopping is idempotent for known debug sandboxes. Exec/stop only accept sandboxes
created by this plugin's debug workflow in the original Modal account; they
cannot target arbitrary sandboxes or provider-managed machines. Stop removes
compute without deleting the shared cached image. Expired IDs remain recognizable.

SDK clients use `sdk.plugins.callRpc` with `modalRpcContract`: `image.build({})`,
`sandbox.run({})`, `sandbox.exec({sandboxId,command})`, and
`sandbox.stop({sandboxId})`. Build/run incur Modal usage.

`bb modal machine inspect HOST_ID [--json]` and the plugin RPC `machine.inspect({ hostId })` read vendor state without waking compute. Sandbox and snapshot identifiers come directly from core’s current persisted machine resource, including lifecycle checkpoints. Existing machines need no diagnostic initialization.

### New thread with a new sandbox

Use `bb thread spawn --project <id> --environment-provider modal-sandbox --prompt "..."`.
The composed environment creates a Modal machine and uses core project-checkout
setup to clone the project. Do not pass machine selectors with this environment.
The same option appears once in the environment picker. Existing sandbox hosts
retain their normal checkout/worktree choices. Machine creation, checkout setup
and environment setup report into the thread's provisioning details. A clone
failure keeps the machine for retry or explicit removal.

## Allocation cleanup

The plugin persists each machine allocation before requesting it from Modal,
then records its sandbox ID when creation returns. This includes resumed
allocations. Debug sandboxes retain their separate ownership and expiry policy.
The once-per-minute plugin sweep checks only these tracked allocations and
imports existing machine sandbox IDs when the plugin starts. Confirmed stopped
allocations are removed from the list; lookup failures and account changes do
not discard ownership. Pending creates can be rediscovered by their saved name;
absent pending entries expire after the requested sandbox lifetime.

When compute is running for a machine core marks suspended, the plugin calls
`hosts.experimental_reconcile` (`bb machine reconcile MACHINE --json`). Core
checks its current state and starts save-and-stop, returning acceptance immediately;
the CLI polls until completion. Core does not poll Modal. Tracking cleanup failures
after a successful stop retain the entry for the next sweep without failing pause.
The idle policy separately calls `hosts.experimental_suspend`. Allocation cleanup
continues when idle pausing is disabled. Allocations without a matching machine
are reported and retained until Modal confirms they are gone.