Skip to content
Get packs

Guide · Agent skill

How to use the Throwaway Machine Sandbox agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The throwaway-machine skill lets an AI agent run code it does not trust, such as a generated script or a pull request's test suite, inside a short-lived smolvm microVM. The repo is mounted read-only, the only writable place is an output folder, and the workload has no network unless you grant it per host. This guide explains what the skill does, how to install and trigger it, what it needs, and where its limits are.

Throwaway Machine Sandboxsmol-machines/smolvm · Apache-2.0

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Install the smolvm CLI. Make sure the smolvm CLI is available. The skill was tested on v1.23.0, and older releases have known cancel and mount bugs.
  3. 3Run the preflight. Run scripts/preflight.sh and read the result= and device_budget_ok= lines before anything else.
  4. 4Bake the image. On the offline route, run scripts/bake.sh python:3.12-alpine with the network on and nothing untrusted mounted.
  5. 5Ask for the isolated run. Describe the untrusted command in a natural request. The agent runs it with scripts/run.sh, which records vm_pid= for cancelling.
  6. 6Verify and clean up. Let the agent run scripts/verify.sh from inside and outside the VM, then scripts/cleanup.sh --purge, or --cancel to stop a run early.

What the skill makes the agent do

The skill runs an untrusted command in a throwaway smolvm microVM against a repository it must not modify. The command's output is collected from a writable output directory. The skill's own description lists three triggers: executing an agent's generated script, testing a pull request's suite in isolation, and running code that should not be trusted with the host.

After each run the agent checks both from inside the VM and from the host that isolation held and that nothing is left running. A run is only treated as done when the output landed, the repo is unchanged, the workload could not reach the network, and no VM is still running.

  • Repo mounted read-only at /workspace (or the path given by --repo-path)
  • Output directory writable at /out
  • No network by default; egress granted one host at a time with --allow-host
  • Cancel support for runs that must be stopped early

Install the skill

Download the ZIP of the skill from this page and unzip it into one of two places. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into .claude/skills/ in the project folder
  • Claude apps: Settings → Capabilities → Skills, then upload

Requirements before you start

The skill needs the smolvm CLI. It was tested on v1.23.0, and the source notes that older releases have known cancel and mount bugs. It also needs a Bash shell and standard Unix tools such as awk, sort and uname, and host access to a container registry for a one-time image bake (python:3.12-alpine by default).

The skill files mention no API keys or accounts.

  • smolvm CLI (tested on v1.23.0)
  • Bash shell with awk, sort, uname
  • Registry access for the one-time bake of python:3.12-alpine
  • Runs scripts: yes. Uses network: yes

How to trigger it with natural requests

Ask in plain language for the thing the skill is for. Name the untrusted thing and say you want it isolated. Examples of requests that match its triggers:

  • Run this script the agent just generated in a sandbox, without touching my repo.
  • Run the test suite of this pull request in isolation.
  • Execute this third-party code, but don't let it reach the network.
  • Let this job reach example.com only, and nothing else.
  • Cancel the sandbox run that is still going.

Walk through a run

The workflow runs in five steps. First, preflight.sh checks the host read-only and reports result= and device_budget_ok=. Second, bake.sh pulls the image once with the network on and nothing untrusted mounted. Third, run.sh runs your command and prints vm_pid=, which is the only route back to the machine if you need to stop it. Fourth, verify.sh checks both inside and outside the guest. Fifth, cleanup.sh removes leftovers, or cancels a run with --cancel.

  • Preflight: scripts/preflight.sh --mounts 2 --ports 0
  • Bake (offline route only): scripts/bake.sh python:3.12-alpine
  • Run: scripts/run.sh --repo ./repo --out ./out -- <command>
  • Verify: scripts/verify.sh --expect-file result.txt --expect 42
  • Clean up: scripts/cleanup.sh --purge
scripts/run.sh --repo ./repo --out ./out -- sh -c 'python3 /workspace/calc.py > /out/result.txt'

Grant network access one host at a time

By default the workload has no network. To allow one host, name it with --allow-host. Verify.sh still probes the shape without a grant, so after a run with --allow-host its inside_network line does not describe that run's egress.

Bake the image before a network-off run. The host CLI still contacts the registry on each --oci-cache run, but the workload does not need network access.

scripts/run.sh --allow-host example.com --repo ./repo --out ./out -- <command>

Know the platform and cancel limits

On macOS from v1.24.0 the offline route does not run: every --oci-cache run fails with agent did not become ready within 30 seconds (issue 1819). The preflight then reports offline_shape=unavailable. For a run with no network on that release, use the persistent machine route in README.md. Windows also lacks the offline shape.

On v1.20.2 and later, Ctrl-C on run.sh ends the run because the script forwards the interrupt to the CLI. Before v1.20.2 use scripts/cleanup.sh --cancel. The --cancel option kills the VMs run.sh recorded and waits up to 20 seconds before asserting nothing is left.

  • Offline route fails on macOS from v1.24.0 (issue 1819)
  • Windows: offline shape unavailable
  • Before v1.20.2: use cleanup.sh --cancel
scripts/cleanup.sh --cancel --purge

What people use it for

  • Running a script an AI agent just generated, with the repo mounted read-only and the output collected from /out.
  • Testing a pull request's test suite in an isolated machine before merging.
  • Running third-party code that should not reach the network, or letting it reach one named host with --allow-host.
  • Stopping a long-running sandboxed job with scripts/cleanup.sh --cancel and confirming no VM is left.

Frequently asked questions

How do I install the throwaway-machine skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills instead.

What do I need to run the throwaway-machine skill?

You need the smolvm CLI (tested on v1.23.0), a Bash shell with standard Unix tools such as awk, sort and uname, and registry access for a one-time image bake of python:3.12-alpine. The skill files mention no API keys or accounts.

Is the throwaway-machine skill free?

The source file does not state pricing or licence terms for the skill itself. The repository it comes from is listed under the Apache-2.0 licence, so check that licence for terms.

Does the sandboxed code have internet access?

No, not by default. The workload has no network unless you grant it, and you can allow one host at a time with --allow-host. Bake the image first so the run pulls nothing over the network.

Why does my run fail on macOS with 'agent did not become ready within 30 seconds'?

On macOS from v1.24.0 the offline route with --oci-cache does not boot, tracked as issue 1819. Run preflight.sh, which reports offline_shape=unavailable there. Use the persistent machine route with no network described in README.md instead.

How is this different from Docker or other sandboxes?

The skill uses smolvm microVMs, which are hardware-isolated virtual machines, and it is built for short throwaway runs. The source says not to use it for a development environment you re-enter across sessions, for running a Docker daemon inside a machine, or for installing smolvm itself.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you want an AI agent to run generated or third-party code, or a pull request's tests, without risking your host, and you can accept that scripts run on your host and isolation depends on smolvm and libkrun working as described. Pick another approach for a long-lived development environment, for a Docker daemon inside a machine, or if you are on Windows or on macOS v1.24.0 or later and need the offline route.

Download the skill