Skip to main content
Porter Sandboxes are isolated container workloads that your application can launch on demand. Use them when a workflow needs a fresh runtime environment for code interpretation, agent tools, batch fan-out, or other dynamic work that may need persistent storage through volumes.
Sandboxes are in a private beta. Please reach out to us at support@porter.run or over Slack if you are interested in joining.

​
When to use sandboxes

  • Untrusted code execution: run code from end users or LLM agents in isolation
  • Agentic tool use: give an LLM a fresh execution environment per task
  • Parallel batch work: fan out many short jobs concurrently
  • On-demand processing: create a runtime for a request, job, or workflow step
For long-running services with ingress, autoscaling, rollouts, and normal application lifecycle management, use Applications instead.

​
Lifecycle

A sandbox moves through these phases: Only running sandboxes accept exec calls. Logs remain available after terminal phases so you can fetch output from completed or terminated sandboxes.

​
Queueing and capacity

Sandbox create returns as soon as the request is durably recorded. If the cluster does not have capacity to launch the sandbox immediately, the sandbox stays in queued until capacity becomes available — create no longer fails on a transient capacity miss. Queued sandboxes are launched in creation order as slots free up, and the warm pool sizes itself against the current queue depth so backlogs drain without manual intervention. Because create is non-blocking, the returned sandbox may still be in the queued or creating phase. Poll refresh() (SDK) or porter sandbox status (CLI) until the phase reaches running before calling exec. Calling exec on a sandbox that is not yet running returns a “sandbox is not running” error rather than blocking.

​
Names

Names are the canonical way to refer to sandboxes and volumes in the SDK and CLI.

​
Build with the Sandbox SDK

Your application creates and manages sandboxes with a Sandbox SDK. For now, we recommend deploying that application as a Porter Application in the same AWS cluster where you want to run sandboxes.

​
Use the CLI for operations

Use the sandbox CLI to inspect and operate on sandboxes from your terminal:
  • Create sandboxes from container images
  • List sandboxes by phase
  • Fetch logs
  • Exec into a running sandbox
  • Terminate one sandbox or many sandboxes at once
  • Create, list, inspect, and delete sandbox volumes
See the sandbox CLI guide.

​
Persistent storage

Volumes provide persistent storage that can be mounted into sandboxes at launch. Create a volume first, then pass volume_mounts when creating a sandbox.

​
Next steps