JavaScript SDK

npm install @ai2in/sdk

TypeScript types included. Node 18+ (uses global fetch). Works in any ESM environment.

Sandbox

import { Sandbox } from "@ai2in/sdk";

const sbx = await Sandbox.create({
  apiKey: "ai2in_live_…",
  baseUrl: "https://api.ai2in.dev", // default
  region: "ap-south-1",
  timeoutMs: 300_000, // optional hard lifetime
  metadata: { session: "agent-42" }, // optional tags (≤2KB)
});

Sandbox.create() is async — it boots the sandbox and resolves once it's ready.

Methods

Method	Returns	Description
runCode(code, opts?)	Promise<Execution>	Run a cell; opts can carry onStdout/onStderr/onResult/onError to stream.
Sandbox.connect(id, opts?)	Promise<Sandbox>	Reconnect to an existing sandbox by id.
Sandbox.list(opts?)	Promise<SandboxInfo[]>	All sandboxes on the engine.
getInfo()	Promise<SandboxInfo>	Status, end_at, paused_at, owning node_id.
setTimeout(ms)	Promise<SandboxInfo>	Auto-kill after N ms from now (max 24h).
pause()	Promise<SandboxInfo>	Stop the container, keep the filesystem.
resume()	Promise<SandboxInfo>	Start it again.
getHost(port)	Promise<string>	Public HTTPS URL for a bound port.
getMetrics()	Promise<Metrics>	Live CPU / memory / pids / uptime.
kill()	Promise<void>	Destroy the sandbox.
commands	object	Shell + background processes (below).
pty	object	Interactive terminals — pty.start() → PtyHandle (send/read/resize/kill).
files	object	Filesystem access (below).

Execution

execution.text        // main result text, or undefined
execution.results     // Result[]
execution.logs        // { stdout: string[], stderr: string[] }
execution.error       // { name, value, traceback } | null

Result carries any of text, html, markdown, svg, png, jpeg, pdf, latex, json, javascript, plus is_main_result.

commands

await sbx.commands.run(cmd);    // -> { stdout, stderr, exitCode }
await sbx.commands.start(cmd);  // -> CommandHandle
await sbx.commands.list();      // -> CommandInfo[]

CommandHandle:

const proc = await sbx.commands.start("npm run dev");
proc.id; proc.pid;
await proc.logs();   // { stdout, stderr, status, exitCode }
await proc.kill();

files

await sbx.files.list(".");             // -> FileEntry[]
await sbx.files.read("app.py");        // -> string
await sbx.files.write("app.py", "…");  // -> void
await sbx.files.upload("data.bin", bytes);   // Uint8Array, ≤32MB
const buf = await sbx.files.download("chart.png"); // -> Uint8Array

const watcher = await sbx.files.watch(".", (e) => {
  console.log(e.type, e.path);         // "create" | "modify" | "remove"
});
await watcher.stop();

Full example

import { Sandbox } from "@ai2in/sdk";

const sbx = await Sandbox.create({ apiKey: "ai2in_live_…" });
await sbx.files.write("app.py", "print('built by an agent')");
console.log((await sbx.commands.run("python3 app.py")).stdout);

await sbx.commands.start("python3 -m http.server 3000");
console.log("preview:", await sbx.getHost(3000));
await sbx.kill();