Agent skill

Modal Sandboxes

by get-bb in get-bb/bb

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

MITAuto-check passedDevOps & Cloud

Install Modal Sandboxes

skills CLI
$ npx skills add get-bb/bb --skill modal-sandboxes -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install get-bb/bb modal-sandboxes --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/get-bb/bb.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/environment-modal-sandbox/skills/modal-sandboxes .claude/skills/modal-sandboxes && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
modal-sandboxes
GitHub stars
4.2k
Token cost
~2.4k tokens
SKILL.md length
1,252 words
Files
1
Skills in repo
33
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 4 steps: Install… → Run bb modal account inspect --json to… → Resolve the project with bb project list… → …
  • DevOps & Cloud work in your project
  • SKILL.md covers Debug an image and Allocation cleanup
  • Calls bash

What it does

Modal Sandboxes is an agent skill from get-bb/bb. Connect Modal and create reusable cloud machines with the bundled standard image, on-demand daemon installation, and snapshot lifecycle.

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud. It works with Docker. The repository describes itself as: The agent IDE that builds itself. The licence is MIT.

When your agent uses it

  • DevOps & Cloud work in your project

Example prompts

  • “/modal-sandboxes”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Install builtin:environment-modal-sandbox and configure tokenId and
  2. Run bb modal account inspect --json to test the connection without allocating
  3. Resolve the project with bb project list --json. It needs a Git remote,
  4. Create a standalone machine with

What it can do on your machine

Read from SKILL.md and the folder at commit 68a1e8b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Modal Sandboxes loads about 2.4k tokens when it runs. Until then it costs about 38 tokens; SKILL.md has 1,252 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~38
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from get-bb/bb at commit 68a1e8b, republished under its MIT licence (© get-bb). 1,252 words, ~2,364 tokens.

Download SKILL.mdSave it as .claude/skills/modal-sandboxes/SKILL.md (or your agent's skills folder).
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.

Show full SKILL.md (614 more words)Show less

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.

© get-bb, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugins/environment-modal-sandbox/skills/modal-sandboxes of get-bb/bb.

Open the folder on GitHubat commit 68a1e8b

Compare with similar skills

Modal Sandboxes next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Modal Sandboxes compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Modal Sandboxes this skillget-bb/bb4.2k—~2.4kAutomated safety check: PassMIT
Iron Proxy Gateway for NanoClawnanocoai/nanoclaw31k—~4.6kAutomated safety check: NotesMIT
GreptimeDB Dev Docker ImageGreptimeTeam/greptimedb6.7k—~4kAutomated safety check: NotesApache-2.0
Senior DevOps Toolkitmaslennikov-ig/claude-code-orchestrator-kit2596 repos~1.1kAutomated safety check: NotesCustom licence
LangBot Deployment Guidelangbot-app/LangBot18k—~1.2kAutomated safety check: NotesApache-2.0
Build Openshell Mxc WindowsNVIDIA/OpenShell15k—~4.9kAutomated safety check: PassApache-2.0

Similar skills

  • Installs or refreshes Iron Proxy and its Iron Control web console for NanoClaw, with a local Docker setup, database, credentials and a human approval bridge.

    31k GitHub stars~4.6k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • GreptimeDB Dev Docker Image

    GreptimeTeam/greptimedb

    Packages a locally built GreptimeDB debug binary into a development-only Docker image for local-cluster testing, with an optional push to a dev registry.

    6.7k GitHub stars~4k tokensUpdated 2 days ago
    DevOps & CloudAuto-check: notes
  • Senior DevOps Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive DevOps skill for CI/CD, infrastructure automation, containerization, and cloud platforms (AWS, GCP, Azure). Includes pipeline setup…

    259 GitHub starsUsed in 6 repos~1.1k tokens
    DevOps & CloudAuto-check: notes
  • LangBot Deployment Guide

    langbot-app/LangBot

    Deploys and configures a LangBot instance with Docker Compose or Kubernetes, covering config.yaml, the Box sandbox runtime, the plugin runtime and the global API key.

    18k GitHub stars~1.2k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Official

    Maintain and validate OpenShell's build-only Windows MSVC lane for x64 and ARM64.

    15k GitHub stars~4.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Container Dev

    yansongda/pay

    A skill your agent uses when local PHP environment is unavailable.

    5.4k GitHub stars~968 tokensUpdated 8 days ago
    DevOps & CloudAuto-check passed

More from get-bb/bb

All 33 skills in this repo
  • Bb CLI

    get-bb/bb

    Inspect or manage BB state with the bb CLI; use for BB commands and configuration.

    4.2k GitHub stars~3.4k tokensUpdated today
    Auto-check passed
  • Skill Creator

    get-bb/bb

    Create or improve BB skills, including their triggers, instructions, and supporting resources.

    4.2k GitHub stars~702 tokensUpdated today
    Auto-check passed
  • Prepare and submit a BB plugin to the Community marketplace when publication or a marketplace PR is requested.

    4.2k GitHub stars~873 tokensUpdated today
    Auto-check passed
  • Workflows

    get-bb/bb

    Author or run durable BB workflows when the user requests workflow execution or multi-agent orchestration.

    4.2k GitHub stars~890 tokensUpdated today
    Auto-check passed
  • Verify Bb

    get-bb/bb

    Verify BB user journeys in an isolated source dev app using dev-browser@next and the matching source CLI.

    4.2k GitHub stars~3.2k tokensUpdated today
    Auto-check passed
  • Create or edit BB color themes and inspect them in the Theme Preview panel.

    4.2k GitHub stars~1.2k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Modal Sandboxes

What does Modal Sandboxes do?

Connect Modal and create reusable cloud machines with the bundled standard image, on-demand daemon installation, and snapshot lifecycle. Modal Sandboxes is an agent skill from get-bb/bb. Connect Modal and create reusable cloud machines with the bundled standard image, on-demand daemon installation, and snapshot lifecycle.

When should I use Modal Sandboxes?

Modal Sandboxes fits situations like: devOps & Cloud work in your project.

How do I install Modal Sandboxes in Claude Code?

Run `npx skills add get-bb/bb --skill modal-sandboxes -a claude-code`. Or copy the skill folder (plugins/environment-modal-sandbox/skills/modal-sandboxes in get-bb/bb) into .claude/skills/modal-sandboxes in your project. Claude Code loads it when a task matches its description.

How do I install Modal Sandboxes in Codex?

Run `npx skills add get-bb/bb --skill modal-sandboxes -a codex`. Or copy the skill folder (plugins/environment-modal-sandbox/skills/modal-sandboxes in get-bb/bb) into .agents/skills/modal-sandboxes in your project. Codex loads it when a task matches its description.

Can I use Modal Sandboxes in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add get-bb/bb --skill modal-sandboxes -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/modal-sandboxes, .gemini/skills/modal-sandboxes, .github/skills/modal-sandboxes and .opencode/skills/modal-sandboxes in your project.

What does Modal Sandboxes need to run?

Going by SKILL.md and its folder, Modal Sandboxes needs the command-line tools its instructions call (bash).

Does Modal Sandboxes access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Modal Sandboxes safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Modal Sandboxes use?

Modal Sandboxes is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Modal Sandboxes use?

About 2.4k tokens (SKILL.md is roughly 9.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Modal Sandboxes?

Skills that share tags, products or a category with Modal Sandboxes: Iron Proxy Gateway for NanoClaw (nanocoai/nanoclaw, 31k stars), GreptimeDB Dev Docker Image (GreptimeTeam/greptimedb, 6.7k stars), Senior DevOps Toolkit (maslennikov-ig/claude-code-orchestrator-kit, 259 stars) and LangBot Deployment Guide (langbot-app/LangBot, 18k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Modal Sandboxes?

get-bb (a GitHub organization) maintains it in get-bb/bb, which has 4,155 GitHub stars. The repository holds 33 skills in this directory. The repository was last updated on October 7, 2026.

Source: get-bb/bb on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.