Commands

Run shell commands in the sandbox. Short commands run to completion; long-running processes run in the background with a handle you can poll or kill.

Run to completion

Python

result = sbx.commands.run("pip install requests")
print(result["stdout"], result["exit_code"])

JavaScript

const result = await sbx.commands.run("pip install requests");
console.log(result.stdout, result.exitCode);

Blocking commands have a 120s timeout — use start for anything longer.

Background processes

start launches a process that outlives the request — a dev server, a build, a watcher. You get a handle back.

Python

proc = sbx.commands.start("python3 -m http.server 3000")
print(proc.id, proc.pid)

logs = proc.logs()          # {stdout, stderr, status, exit_code}
print(logs["stdout"])

proc.kill()                 # SIGTERM to the process group

JavaScript

const proc = await sbx.commands.start("python3 -m http.server 3000");
console.log(proc.id, proc.pid);

const logs = await proc.logs(); // { stdout, stderr, status, exitCode }
await proc.kill();

List everything running:

Python

for c in sbx.commands.list():
    print(c["command_id"], c["cmd"], c["status"])

JavaScript

for (const c of await sbx.commands.list()) {
  console.log(c.commandId, c.cmd, c.status);
}

Working directory & environment

Both run and start accept a working directory and extra env vars:

Python

sbx.commands.run("npm test", cwd="app", env={"CI": "1"})
sbx.commands.start("npm run dev", cwd="app", env={"PORT": "3000"})

JavaScript

await sbx.commands.run("npm test", { cwd: "app", env: { CI: "1" } });
await sbx.commands.start("npm run dev", { cwd: "app", env: { PORT: "3000" } });

Interactive terminal (PTY)

For a real terminal — line editing, colors, interactive programs — start a PTY. send() types into it; read() drains output (poll it on a timer):

Python

term = sbx.pty.start(cols=120, rows=30)
term.send("ls -la\n")
out = term.read()          # {"data": bytes, "alive": bool, "exit_code": None}
print(out["data"].decode())
term.kill()

JavaScript

const term = await sbx.pty.start({ cols: 120, rows: 30 });
await term.send("ls -la\n");
const { text, alive } = await term.read();
await term.kill();

Or from your own terminal, one command: ai2in shell <sandbox-id> gives you a live bash inside the sandbox (Ctrl+] detaches).

Pattern: run a server, preview it

Background commands pair with preview URLs: start a server, then expose its port to get a public link.

sbx.commands.start("python3 -m http.server 3000")
url = sbx.get_host(3000)     # https://3000-<id>.up.ai2in.dev
print(url)