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 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.

​
Sandbox lifetime

A sandbox lives as long as its main process: the image’s default entrypoint, or the command you pass at create time. When that process exits with code 0 the sandbox moves to succeeded; a nonzero exit moves it to failed. Once the sandbox reaches either phase, exec calls fail. This means an image whose default command exits immediately reaches succeeded within a few seconds of starting. To keep a sandbox alive so you can exec into it, give it a long-running main process and terminate it when you’re done:

​
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.

​
Networking

A sandbox that opens a port can be served over HTTPS on a hostname under your own domain, with public or private networking configured on the cluster. See Sandbox Networking.

​
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