Skip to main content

Sandboxes

Sandboxes are isolated microVM environments where code runs. Each sandbox gets its own kernel, filesystem, and network stack.

What is a sandbox​

A sandbox is a lightweight virtual machine that boots in under 200ms. When you call vm.execute(), InstaVM provisions a sandbox, runs your code, and returns the result. Sandboxes are fully isolated from each other and from the host.

Each sandbox includes:

  • A Linux kernel (based on Firecracker microVMs)
  • A writable filesystem with common tools pre-installed
  • Python 3.11+ with pip
  • Network access (configurable via egress policies)
  • /app as the default working directory

Resource configuration​

Configure CPU and memory when creating a client:

from instavm import InstaVM

with InstaVM(api_key='your_api_key', cpu_count=4, memory_mb=4096) as vm:
    result = vm.execute("import multiprocessing; print(multiprocessing.cpu_count())")
    # Output: 4

Defaults​

ResourceDefaultRange
vCPUs21-8
Memory512 MB256-8192 MB

Lifecycle​

  1. Boot -- A sandbox provisions when you first call execute() or explicitly create a session.
  2. Active -- The sandbox runs your code. State persists between execute() calls within the same session.
  3. Terminated -- The sandbox is destroyed when the session ends, when you call kill(), or when the lifetime expires.

Base images​

The default sandbox image includes:

  • Python 3.11+ with pip
  • Node.js 18+
  • Common system packages (curl, wget, git, build-essential)
  • ffmpeg, imagemagick

For custom environments, create a snapshot from an OCI image with your own dependencies pre-installed.

Environment variables​

Inject environment variables at creation time:

with InstaVM(api_key='your_api_key', env={"DATABASE_URL": "postgres://..."}) as vm:
    result = vm.execute("import os; print(os.getenv('DATABASE_URL'))")

Security model​

  • Each sandbox runs in its own microVM with a dedicated kernel
  • No shared filesystem or memory between sandboxes
  • Network egress is deny-by-default and configurable per-session or per-VM
  • Root access inside the sandbox does not grant access to the host

Next steps​