Concepts
Sandboxes
Isolated execution environments powered by Firecracker
What is a Sandbox?
A sandbox is an isolated microVM that provides a secure environment for running code. Each sandbox has its own:
- Filesystem — Isolated ext4 filesystem with NVMe storage
- Network — Private networking stack
- Memory — Dedicated RAM allocation
- CPU — Isolated CPU resources
Creating a Sandbox
import { Sandbox } from '@iris/sdk'
// Reads IRIS_API_KEY from environment
const sandbox = await Sandbox.create()
// Optional: give it a name for easier identification
const named = await Sandbox.create({ name: 'my-agent' })For multi-sandbox workflows you can also use IrisClient directly:
import { IrisClient } from '@iris/sdk'
const client = new IrisClient({ apiKey: process.env.IRIS_API_KEY })
const sandboxes = await client.sandboxes.list()Sandbox Lifecycle
fork() creates a new independent sandbox using copy-on-write — the original keeps running. Use it to branch at any execution point.
Under the Hood
Iris sandboxes are powered by Firecracker, the same technology used by AWS Lambda and Fargate.
Key characteristics:
- ~125ms boot time — Fast cold starts
- Hardware isolation — Each sandbox runs in its own microVM
- Minimal overhead — ~5MB memory footprint per VM
- Secure by default — No shared kernel state between sandboxes