Sandbox

Isolated, ephemeral execution environments for running code safely — with configurable resource limits and security controls.

Outpost Sandboxes are lightweight, isolated compute environments for executing arbitrary code. Each sandbox is a container or microVM with hard limits on CPU, memory, disk, and execution time. Sandboxes are designed for running untrusted or AI-generated code without affecting the host system.

Key features

Process isolation — seccomp syscall filtering and optional Firecracker microVM jailer keep execution contained.
Ephemeral or stateful — ephemeral sandboxes reset to a clean state after each execution; stateful sandboxes retain filesystem state across runs.
Async job queue — submit code and poll for results. Useful for high-throughput pipelines.
Language runtimes — specify the runtime language (python, node, rust, go) and optional container image.
Resource limits — cap memory, CPU, disk, and timeout per sandbox or per execution.

Quick start

# Create a Python sandbox
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "language": "python",
    "mode": "stateful",
    "resource_limits": {"memory_mb": 512, "cpu_cores": 1, "timeout_ms": 30000}
  }'
 
# Execute code in it
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox/<id>/exec 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"code": "print(2 + 2)"}'

# Create a Python sandbox
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "language": "python",
    "mode": "stateful",
    "resource_limits": {"memory_mb": 512, "cpu_cores": 1, "timeout_ms": 30000}
  }'
 
# Execute code in it
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox/<id>/exec 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"code": "print(2 + 2)"}'

How it works

Create — provision a sandbox with a language runtime and resource limits.
Execute — submit code to the sandbox. Outpost runs it in isolation and returns stdout, stderr, and exit code.
Reuse or discard — stateful sandboxes persist state between executions; ephemeral sandboxes reset after each run.
Delete — destroy the sandbox to release resources.

Execution modes

Mode	Behavior
`ephemeral`	Sandbox resets to a clean state after each execution. No filesystem state persists.
`stateful`	Filesystem and installed packages persist between executions.

Use ephemeral for untrusted user code or isolated one-shot tasks. Use stateful when you need to install dependencies once and run multiple executions against the same environment.

Async execution

For long-running code, use the job queue instead of the synchronous exec endpoint:

# Submit a job (returns immediately)
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox/jobs 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"language": "python", "code": "import time; time.sleep(10); print("done")"}'
 
# Poll for result
curl https://outpost.run/auth/v1/seed/acme/sandbox/<sandbox_id>/jobs/<job_id> 
  -H "Authorization: Bearer $TOKEN"

# Submit a job (returns immediately)
curl -X POST https://outpost.run/auth/v1/seed/acme/sandbox/jobs 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"language": "python", "code": "import time; time.sleep(10); print("done")"}'
 
# Poll for result
curl https://outpost.run/auth/v1/seed/acme/sandbox/<sandbox_id>/jobs/<job_id> 
  -H "Authorization: Bearer $TOKEN"

Security

Sandboxes support multiple isolation layers:

seccomp — restricts available syscalls using a kernel-level filter.
jailer — Firecracker microVM isolation for full kernel separation. Recommended for AI-generated or user-submitted code.
user — run the sandbox process as a non-root user.

Use cases

AI code execution — safely run code generated by LLMs without exposing host infrastructure.
CI tasks — run test suites, linters, or build steps in isolated environments.
Online judges — evaluate user-submitted code for competitive programming or educational platforms.
Notebook kernels — power interactive notebook-style code execution with state persistence.

CLI reference

Command	Description
`outpost sandbox launch`	Launch a new sandbox
`outpost sandbox list`	List all sandboxes
`outpost sandbox status`	Get sandbox status
`outpost sandbox delete`	Delete a sandbox

Next steps

Create a sandbox — API reference for provisioning
Execute code — run code inside a sandbox
Submit a job — async job queue API

Previous → Load Balancer

Next Overview →