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:
PhaseDescription
queuedThe sandbox was accepted and is waiting for capacity.
creatingPorter is preparing the runtime and starting the container.
runningThe sandbox is ready and can accept exec calls.
succeededThe sandbox command completed successfully.
failedThe sandbox command or runtime failed.
terminatedThe sandbox was explicitly terminated through the API, SDK, or CLI.
Only running sandboxes accept exec calls. Logs remain available after terminal phases so you can fetch output from completed or terminated sandboxes.

​
Names

Names are the canonical way to refer to sandboxes and volumes in the SDK and CLI.
ResourceNaming rule
SandboxSandbox names must be unique within a cluster and currently cannot be reused, even after the sandbox is terminated. Omit the name only for one-off sandboxes where you do not need stable lookup later.
VolumeVolume names must be unique within a cluster for the lifetime of the volume. After a volume is deleted, its name can be used again.

​
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