Sandboxes

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

create() → running
              ↓
         fork() → new running sandbox (copy-on-write)
              ↓
         checkpoint.create() → checkpoint saved (sandbox keeps running)
              ↓
         suspend() → suspended
              ↓
         resume() → running
              ↓
         kill() → terminated

Note

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