sandbox_skill

Overview

This skill creates and manages isolated container sandboxes for executing AI agent code and testing workflows. It supports both cold sandboxes for simple, ephemeral runs and pre-warmed hot pools for near-instant acquisition. Use it to run untrusted code, perform iterative stateful workflows, or expose services for agent testing in a controlled environment.

How this skill works

The SDK provisions containers on DigitalOcean App Platform using predefined images (python/node) or custom images. You can create single cold sandboxes (~30s startup) or run a SandboxManager to maintain a hot pool of pre-warmed sandboxes (~50–500ms acquire). It exposes APIs for executing commands, streaming output, managing files, exposing ports, snapshotting (hibernate), and lifecycle cleanup.

When to use it

• Run untrusted or third-party agent code in isolation.
• Execute multi-step, stateful agent workflows that need persistence across steps.
• Interactive or iterative development where agents install packages and modify state.
• Low-latency interactive agents—use a hot pool for instant responses.
• One-off script tests and CI jobs where per-job isolation is needed.

Best practices

• Always call sandbox.delete() when you finish to avoid billing surprises.
• Use SandboxManager pools for interactive workloads to eliminate cold-start delay.
• Prefer cold sandboxes for single-run CI or short-lived tasks to reduce overhead.
• Use sandbox.hibernate() + Sandbox.wake() to persist expensive setup and lower runtime cost.
• Expose ports and exec_stream() only for SERVICE mode sandboxes; use exec() for short commands.

Example use cases

• Run a code-executing AI assistant that needs to install packages and iterate on output.
• Test an agent workflow that launches a local HTTP server and needs a stable working directory.
• Pre-warm a pool for a user-facing interpreter feature that requires sub-second responsiveness.
• CI job that runs tests in a fresh environment using a cold sandbox per job.
• Snapshot a configured environment, hibernate it, and wake it later to resume long-running experiments.