Python SDK

pip install ai2in

Stdlib-only — no third-party dependencies. Python 3.9+.

Sandbox

from ai2in import Sandbox

sbx = Sandbox(
    api_key="ai2in_live_…",
    base_url="https://api.ai2in.dev",  # default
    region="ap-south-1",
    timeout=300,                        # optional hard lifetime (seconds)
    metadata={"session": "agent-42"},  # optional tags (≤2KB)
)

A sandbox is created on construction. Use it as a context manager to auto-kill:

with Sandbox(api_key="…") as sbx:
    sbx.run_code("print('hi')")

Methods

Method	Returns	Description
run_code(code, on_stdout=…, on_stderr=…, on_result=…, on_error=…)	Execution	Run a cell in the stateful kernel; pass callbacks to stream.
Sandbox.connect(id, api_key=…)	Sandbox	Reconnect to an existing sandbox by id.
Sandbox.list(api_key=…)	list	All sandboxes on the engine (running + paused).
get_info()	dict	Status, end_at, paused_at, owning node_id.
set_timeout(seconds)	dict	Auto-kill after N seconds from now (max 24h).
pause()	dict	Stop the container, keep the filesystem.
resume()	dict	Start it again.
get_host(port)	str	Public HTTPS URL for a bound port.
get_metrics()	dict	Live CPU / memory / pids / uptime.
kill()	None	Destroy the sandbox.
commands	_Commands	Shell + background processes (below).
pty	_Pty	Interactive terminals — pty.start() → PtyHandle (send/read/resize/kill).
files	_Files	Filesystem access (below).

Execution

execution.text        # main result text, or None
execution.results     # list[Result]
execution.logs        # Logs(stdout=[...], stderr=[...])
execution.error       # {"name", "value", "traceback"} or None

Result fields: text, html, markdown, svg, png, jpeg, pdf, latex, json, javascript, is_main_result.

commands

sbx.commands.run(cmd)      # blocking -> {"stdout", "stderr", "exit_code"}
sbx.commands.start(cmd)    # background -> CommandHandle
sbx.commands.list()        # -> list of {command_id, cmd, pid, status, exit_code}

CommandHandle:

proc = sbx.commands.start("npm run dev")
proc.id            # "cmd_…"
proc.pid           # int
proc.logs()        # {"stdout", "stderr", "status", "exit_code"}
proc.kill()        # SIGTERM to the process group

files

sbx.files.list(path=".")            # -> [{"name", "type", "size"}, ...]
sbx.files.read(path)                # -> str
sbx.files.write(path, content)      # -> {"path", "written"}
sbx.files.upload(path, data: bytes)  # binary upload (≤32MB)
sbx.files.download(path) -> bytes    # binary download (≤32MB)
sbx.files.watch(path=".", recursive=True)  # -> Watcher

Watcher:

w = sbx.files.watch(".")
w.poll()   # -> [{"type": "create|modify|remove", "path": "..."}]
w.stop()

Full example

from ai2in import Sandbox

with Sandbox(api_key="ai2in_live_…") as sbx:
    sbx.files.write("app.py", "print('built by an agent')")
    print(sbx.commands.run("python3 app.py")["stdout"])

    sbx.commands.start("python3 -m http.server 3000")
    print("preview:", sbx.get_host(3000))