Cookbook

Run a shell command and check output

import { Sandbox } from '@iris/sdk'

const sandbox = await Sandbox.create()

const result = await sandbox.exec.run('python3 --version')

if (result.ok) {
  console.log(result.stdout.trim()) // "Python 3.x.x"
} else {
  console.error('Failed:', result.stderr)
}

await sandbox.kill()

Write a file, execute it, read the output

const sandbox = await Sandbox.create()

await sandbox.files.write('/tmp/hello.py', 'print("hello from iris")\n')

const result = await sandbox.exec.run({
  cmd: ['python3', '/tmp/hello.py'],
  dir: '/tmp',
})

console.log(result.stdout) // "hello from iris\n"

await sandbox.kill()

Fork for safe experimentation

const sandbox = await Sandbox.create()
await sandbox.exec.run('npm install express')

// Fork before the risky step — original is untouched
const branch = await sandbox.fork()
const result = await branch.exec.run('rm -rf node_modules')
await branch.kill()

// Original still has node_modules
const check = await sandbox.exec.run('ls node_modules | wc -l')
console.log(check.stdout.trim()) // non-zero

await sandbox.kill()

Parallel experiments from the same base

const sandbox = await Sandbox.create()
await sandbox.exec.run('pip install numpy')

const configs = [
  { lr: '0.001', epochs: '10' },
  { lr: '0.01',  epochs: '10' },
  { lr: '0.1',   epochs: '10' },
]

const results = await Promise.all(
  configs.map(async ({ lr, epochs }) => {
    const branch = await sandbox.fork()
    const result = await branch.exec.run({
      cmd: ['python3', 'train.py'],
      env: { LR: lr, EPOCHS: epochs },
      timeout_ms: 120_000,
    })
    await branch.kill()
    return { lr, output: result.stdout, ok: result.ok }
  }),
)

console.log(results)
await sandbox.kill()

Checkpoint after setup, fork for each run

const sandbox = await Sandbox.create()

// Expensive setup — do it once
await sandbox.exec.run('pip install -r requirements.txt')
await sandbox.exec.run('python3 seed_data.py')

const cp = await sandbox.checkpoint.create({ name: 'ready' })
console.log('Checkpoint:', cp.checkpoint_id)

// Fork from the live sandbox for subsequent runs
for (const input of inputs) {
  const run = await sandbox.fork()
  await run.files.write('/tmp/input.json', JSON.stringify(input))
  const result = await run.exec.run('python3 process.py /tmp/input.json')
  console.log(input.id, result.stdout)
  await run.kill()
}

await sandbox.kill()

List and manage sandboxes

import { IrisClient } from '@iris/sdk'

const client = new IrisClient()  // reads IRIS_API_KEY from env

const sandboxes = await client.sandboxes.list()
console.log('Running sandboxes:', sandboxes.length)

for (const sb of sandboxes) {
  console.log(sb.id, sb.name, sb.state)
}

// Suspend a sandbox to stop billing while keeping state
await client.sandboxes.suspend(sandboxes[0].id)

// Resume it later
await client.sandboxes.resume(sandboxes[0].id)

Run a persistent background service

const sandbox = await Sandbox.create()

// Start a Redis-compatible KV server
await sandbox.services.upsert('redis', {
  cmd: 'redis-server',
  args: ['--port', '6379'],
})
await sandbox.services.start('redis')

// Wait for it to be ready, then run tests against it
const result = await sandbox.exec.run('redis-cli ping')
console.log(result.stdout) // "PONG\n"

await sandbox.kill()

Use the sandbox KV store

const sandbox = await Sandbox.create()

// Store agent state between steps (values are JSON — stringify to store complex objects)
await sandbox.store.set('progress', { value: { step: 1, score: 0.82 } })

const entry = await sandbox.store.get('progress')
const state = entry.value as { step: number; score: number }
console.log('Step:', state.step)

const all = await sandbox.store.list()
console.log('Keys:', all.keys)

await sandbox.kill()

Checkpoint and restore in-place

const sandbox = await Sandbox.create()
await sandbox.exec.run('pip install numpy')

// Save this state
const cp = await sandbox.checkpoint.create({ name: 'clean' })

// Do something destructive
await sandbox.exec.run('pip uninstall -y numpy')

// Roll back — same sandbox, state rewound
const restore = await sandbox.checkpoint.restore(cp.checkpoint_id)
console.log(`Restored in ${restore.restore_duration_ms}ms`)

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

await sandbox.kill()