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 currently only available on AWS.

​
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:
You can also bound a sandbox’s lifetime up front with a TTL, so it cleans itself up even if its main process never exits. Pass ttl_seconds in the SDKs or --ttl on the CLI at create time. The TTL counts from creation; shortly after it elapses, Porter terminates the sandbox the same way an explicit terminate does, moving it to terminated:

​
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
  • Snapshot a running sandbox and start new sandboxes from it
  • 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. See Volumes for creating, mounting, reading, writing, and managing them.

​
Snapshots

A snapshot captures a running sandbox’s filesystem so you can start new sandboxes from it later, with the same files in place. Use it to save an environment after a setup step, such as installing dependencies or cloning a repository, and then start many sandboxes from that point instead of repeating the setup in each one. Capturing does not stop the sandbox. A snapshot holds files only, not running processes or mounted volumes: a sandbox started from a snapshot runs its command from the beginning, and mounts only the volumes you pass at create time. Snapshot from the SDKs or the CLI:

​
Monitoring

To see how much CPU and memory a running sandbox is using, and how close it is to its limits, run porter sandbox metrics. It reports p50 and p90 CPU and memory usage over a lookback window, with per-limit utilization.

​
Next steps