Create & Execute

Use this pattern for one-shot tasks and short workflows.

Quick examples

from isorun import Sandbox

with Sandbox("python") as sb:
    result = sb.exec("python3 -c 'print(2**100)'")
    print(result.stdout.strip())
    print(result.exit_code)

import { Sandbox } from 'isorun'

const sb = await Sandbox.create('python')
try {
  const result = await sb.exec("python3 -c 'print(2**100)'")
  console.log(result.stdout.trim())
  console.log(result.exitCode)
} finally {
  await sb.close()
}

RUN_ID=$(curl -sS -X POST https://api.isorun.ai/v1/runs \
  -H "Authorization: Bearer $ISORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"python"}' | jq -r .id)

curl -sS -X POST "https://api.isorun.ai/v1/runs/$RUN_ID/exec" \
  -H "Authorization: Bearer $ISORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"python3 -c \"print(2**100)\"","timeout":30}'

curl -sS -X DELETE "https://api.isorun.ai/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $ISORUN_API_KEY"

exec vs execStream

Method	Best for	Tradeoff
exec	Short bounded commands	No incremental output while running
execStream	Long builds/tests/training	Slightly more integration code

Failure handling

result = sb.exec("pytest -q", timeout=180)
if result.exit_code != 0:
    print(result.stderr)
    raise RuntimeError("tests failed")

Cleanup and cost control

Always destroy or close sandboxes in finally/context-manager paths.

• Prevents leaked runtime costs.
• Keeps capacity available under load.
• Makes behavior predictable in production.

Next: Lifecycle and Checkpoints & Rollback.