modal-sandboxes

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