Quickstart

This guide gets you from a new project to your first successful code execution in a Runra sandbox.

Prerequisites

• Node.js 18+ or Bun.
• A Runra API key from the Runra dashboard.
• Optional: a template ID if you want to use a custom sandbox image.

1. Install the SDK

npm install runra
# or
bun add runra

2. Configure your API key

Create a .env file or export the variables in your shell:

export RUNRA_API_KEY=runra_your_api_key
# Optional. Defaults to https://box.runra.dev
export RUNRA_API_URL=https://box.runra.dev
# Optional. Use a prebuilt template instead of the default template.
export RUNRA_TEMPLATE_ID=tpl_default

3. Create a sandbox

Create quickstart.ts:

import { Sandbox } from "runra";

const sbx = await Sandbox.create({
  timeout: 300, // seconds
});

console.log(`Sandbox created: ${sbx.sandboxId}`);

Sandbox.create() returns an E2B-compatible sandbox object. You can use runCode() for notebook-style code execution and commands.run() for shell commands.

4. Run Python code

const execution = await sbx.runCode(`
name = "Runra"
print(f"hello from {name}")
2 + 2
`);

console.log(execution.logs.stdout.join("\n"));
console.log("Result:", execution.text);

Expected output:

hello from Runra
Result: 4

5. Run shell commands

const result = await sbx.commands.run("python --version && pwd");

console.log(result.stdout);
if (result.stderr) console.error(result.stderr);

6. Clean up

Terminate the sandbox when you no longer need it:

await sbx.kill();

A complete script should wrap work in try/finally so cleanup still runs if your code throws.

import { Sandbox } from "runra";

const sbx = await Sandbox.create({ timeout: 300 });

try {
  const execution = await sbx.runCode('print("hello from Runra")');
  console.log(execution.logs.stdout.join("\n"));

  const command = await sbx.commands.run("python --version");
  console.log(command.stdout);
} finally {
  await sbx.kill();
}

Run it:

npx tsx quickstart.ts
# or
bun run quickstart.ts

Next steps

• Connect LLMs - give an LLM a sandbox execution tool.
• Upload and download files - move files in and out of a sandbox.
• Install custom packages - add Python or Node dependencies.