Skip to content
Isorun Docs

Quickstart

from isorun import Sandbox


with Sandbox("python") as sb:
    result = sb.exec("python3 -c 'print(sum(range(10**7)))'")
    print(result.stdout)  # 49999995000000

Install

Terminal window
pip install isorun
Terminal window
npm install isorun

API key

Set ISORUN_API_KEY in your environment. Get one from the dashboard.

Terminal window
export ISORUN_API_KEY=isorun_live_<region>_<id>_<hmac>

That’s it. Each Sandbox() boots a Firecracker microVM in ~27 ms with its own kernel, 1 GiB RAM, and 10 GiB CoW disk. The with block destroys it on exit.

The four primitives that make isorun different

Most runtimes stop at “boot fast, run code, destroy.” Isorun adds four primitives that change what AI agents can do inside a sandbox:

1. Long-lived shell sessions — 0.13 ms per command

with Sandbox("python") as sb, sb.shell() as sh:
    sh.run("cd /tmp")            # cwd persists
    sh.run("export FOO=bar")     # env persists
    print(sh.run("echo $FOO").stdout)  # bar

State is shared across commands inside the same session. 30-60× faster than sb.exec() per call. Read more →

2. Forking — clone a running sandbox in ~16 ms per child

parent = Sandbox("python")
parent.create()
parent.exec("pip install transformers torch")  # 30s of setup


# 5 forks inherit the loaded packages AND the model weights in
# memory — no re-install, no re-load.
children = parent.fork(count=5)
for c in children:
    c.exec("python3 evaluate_hypothesis.py")

Children inherit filesystem state AND running process state. The AI-agent backtracking primitive. Read more →

3. Public URLs — expose any in-sandbox port to the internet

sb.exec("nohup setsid jupyter notebook --port 8888 \
  --no-browser --ip 0.0.0.0 --NotebookApp.token='' >/dev/null 2>&1 &")


print(sb.url(port=8888))
# → https://run<id>.isorun.ai/sb/p/8888/

Anonymous public URL, WebSocket-aware (Vite HMR, Jupyter, gradio all work). Anyone with the URL can hit the in-sandbox server. Read more →

4. Hibernate / Resume — persistent workspaces at zero idle cost

sb.hibernate()  # ~470 ms — frees the FC process / TAP / cgroup
# … hours later …
sb.resume()     # ~21 ms — faster than a cold create

The user perceives a workspace that’s always there. The runner only spends resources when it’s actually running. Filesystem, memory, and running processes all survive. Read more →