Quickstart

Installation

npm

npm install @iris/sdk

pnpm

pnpm add @iris/sdk

yarn

yarn add @iris/sdk

Get your API Key

1. Sign up — Create an account at app.irisrun.io using GitHub or email.

2. Navigate to API Keys — Go to Settings → API Keys in your dashboard.

3. Set environment variable

   export IRIS_API_KEY=your_api_key

Create your first Sandbox

Sandbox.create() reads IRIS_API_KEY from the environment automatically.

import { Sandbox } from '@iris/sdk'

async function main() {
  const sandbox = await Sandbox.create()

  console.log('Sandbox created:', sandbox.id)

  const result = await sandbox.exec.run('echo "Hello from Iris!"')
  console.log(result.stdout) // "Hello from Iris!\n"

  await sandbox.kill()
}

main()

Checkpoint and Fork

Checkpoint the sandbox state, then fork from that point for safe experimentation:

import { Sandbox } from '@iris/sdk'

async function main() {
  const sandbox = await Sandbox.create()

  // Install dependencies
  await sandbox.exec.run('apt-get install -y python3-numpy')

  // Save this state
  const cp = await sandbox.checkpoint.create({ name: 'deps-installed' })
  console.log('Checkpoint saved:', cp.checkpoint_id)

  // Fork to run something risky — original sandbox is untouched
  const branch = await sandbox.fork()
  await branch.exec.run('python3 -c "import os; os.system(\"rm -rf /tmp\")"')
  await branch.kill()

  // Original sandbox still has numpy
  const check = await sandbox.exec.run('python3 -c "import numpy; print(numpy.__version__)"')
  console.log(check.stdout)

  await sandbox.kill()
}

main()

Next Steps

Core Concepts Learn about sandboxes, execution, and checkpoints

AI Agents Guide Build AI agents with safe code execution