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:

CLI

instavm create --vcpu 4 --memory 4096

Python

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

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key', { cpuCount: 4, memoryMb: 4096 });
const result = await client.execute("import multiprocessing; print(multiprocessing.cpu_count())");
// Output: 4
await client.dispose();

Defaults

Resource	Default	Range
vCPUs	2	1-8
Memory	512 MB	256-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:

CLI

instavm create
# Then connect and set environment variables
instavm connect <vm_id>
# Inside the VM:
# export DATABASE_URL="postgres://..."

Python

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

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key', {
  env: { DATABASE_URL: 'postgres://...' },
});
const result = await client.execute("import os; print(os.getenv('DATABASE_URL'))");
await client.dispose();

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

• Sessions -- how sessions map to sandboxes
• Egress Policies -- controlling network access
• Snapshots -- custom base images for faster starts