SDK Reference

npm install @banata-boxes/sdk
# or
bun add @banata-boxes/sdk
# or
yarn add @banata-boxes/sdk

import \{ BrowserCloud \} from "@banata-boxes/sdk";
 
const cloud = new BrowserCloud(\{
  apiKey: "br_live_...",       // Required
  baseUrl: "https://...",      // Default: "https://api.boxes.banata.dev"
  appUrl: "https://boxes.banata.dev", // Optional public app host for viewer URLs
  retry: \{
    maxRetries: 3,             // Default: 3
    baseDelayMs: 500,          // Default: 500
    maxDelayMs: 10000,         // Default: 10,000
  \},
\});

const \{ cdpUrl, sessionId, previewViewerUrl, close \} = await cloud.launch(\{
  weight: "light",
  stealth: true,
  recording: true,
  timeout: 30000,
\});
 
// Use cdpUrl with Puppeteer, Playwright, or any CDP client
const browser = await puppeteer.connect(\{ browserWSEndpoint: cdpUrl \});
 
// Or hand a human the standalone viewer URL
console.log(previewViewerUrl);
 
// Clean up when done
await browser.disconnect();
await close();

const session = await cloud.createBrowser(\{ weight: "medium" \});
// session.id, session.status === "queued"

const session = await cloud.getBrowser("session-id");
// session.status, session.cdpUrl, session.artifacts

await cloud.closeBrowser("session-id");

const cdpUrl = await cloud.waitForReady("session-id", 30000);

import \{ BanataSandbox \} from "@banata-boxes/sdk";
 
const sandbox = new BanataSandbox(\{
  apiKey: "br_live_...",       // Required
  baseUrl: "https://...",      // Default: "https://api.boxes.banata.dev"
  appUrl: "https://boxes.banata.dev", // Optional public app host for standalone viewers
  retry: \{
    maxRetries: 3,
    baseDelayMs: 500,
    maxDelayMs: 10000,
  \},
\});

const session = await sandbox.launch(\{
  runtime: "bun",
  size: "standard",
  capabilities: \{
    opencode: \{ enabled: true, defaultAgent: "build", allowPromptApi: true \},
    browser: \{
      mode: "local-chromium",
      streamPreview: true,
      humanInLoop: true,
      viewport: \{ width: 1280, height: 800 \},
    \},
  \},
\});
 
// Execute commands
const result = await session.exec("echo", ["Hello from sandbox!"]);
console.log(result.stdout); // "Hello from sandbox!"
 
// Run code
const code = await session.runCode("console.log(1 + 1)");
console.log(code.stdout); // "2"
 
// Read/write files
await session.fs.write("/workspace/hello.txt", "Hello!");
const content = await session.fs.read("/workspace/hello.txt");
const files = await session.fs.list("/workspace");
 
// AI agent prompt (requires opencode capability)
const response = await session.prompt("Create a simple web server");
 
// Start or resize the live browser preview if needed
await session.startPreview();
await session.resizePreview(\{ width: 1100, height: 720 \});
console.log(session.browserPreviewViewerUrl);
 
// Read OpenCode state or stream events
const state = await session.getOpencodeState(\{ ensureSession: true \});
 
// Create a checkpoint (snapshot)
const checkpoint = await session.checkpoint();
 
// Clean up
await session.kill();

const session = await sandbox.create(\{ runtime: "python", size: "standard" \});
// session.id, session.status === "queued"

const session = await sandbox.get("sandbox-id");
// session.status, session.terminalUrl, session.opencode, session.browserPreviewViewerUrl, etc.

const sessions = await sandbox.list();

await sandbox.kill("sandbox-id");

const result = await sandbox.exec("sandbox-id", "ls", ["-la", "/workspace"]);
// result.stdout, result.stderr, result.exitCode, result.durationMs

const result = await sandbox.runCode("sandbox-id", "print('Hello from Python!')");

await sandbox.pause("sandbox-id");
// ... later ...
await sandbox.resume("sandbox-id");

// Read a file
const content = await sandbox.fs.read("sandbox-id", "/workspace/app.ts");
 
// Write a file
await sandbox.fs.write("sandbox-id", "/workspace/app.ts", "console.log('hello')");
 
// List directory
const entries = await sandbox.fs.list("sandbox-id", "/workspace");
// entries: [\{ name: "app.ts", type: "file", size: 22, mtime: ... \}]

const \{ terminalUrl, token \} = await sandbox.terminal("sandbox-id");
// Connect via WebSocket: new WebSocket(terminalUrl)

const response = await sandbox.prompt("sandbox-id", "Create a REST API with Express", \{
  agent: "build",     // "build" or "plan"
  noReply: false,      // Set true for fire-and-forget
\});

await sandbox.promptAsync("sandbox-id", "Open example.com and summarize the page", \{
  agent: "build",
\});

const state = await sandbox.getOpencodeState("sandbox-id", \{
  ensureSession: true,
  agent: "build",
\});
 
const messages = await sandbox.listOpencodeMessages("sandbox-id");
 
for await (const event of sandbox.streamOpencodeEvents("sandbox-id")) \{
  console.log(event.type, event.data);
  if (event.type === "session.idle") break;
\}

const result = await sandbox.checkpoint("sandbox-id");
// result.ok, result.artifacts

const \{ artifacts \} = await sandbox.getArtifacts("sandbox-id");
const download = await sandbox.getArtifactDownloadUrl("sandbox-id", artifacts.outputLogKey);
// download.url — presigned download URL

// Request human assistance
const handoff = await sandbox.requestHumanHandoff("sandbox-id", \{
  reason: "mfa",
  message: "MFA code required for login",
  resumePrompt: "Continue after MFA is completed",
  expiresInMs: 300000, // 5 minutes
\});
 
// Human accepts and takes control
const accepted = await sandbox.acceptHumanHandoff("sandbox-id", \{
  controller: "operator@example.com",
  leaseMs: 120000,
\});
 
// Human completes the task
const completed = await sandbox.completeHumanHandoff("sandbox-id", \{
  note: "MFA code entered successfully",
  returnControlTo: "ai",
  runResumePrompt: true, // Runs the resumePrompt from the request
\});

// Set browser to human control
await sandbox.setControl("sandbox-id", "human", \{
  controller: "user@example.com",
  leaseMs: 60000,
\});
 
// Return to AI control
await sandbox.setControl("sandbox-id", "ai");
 
// Shared mode (both AI and human can interact)
await sandbox.setControl("sandbox-id", "shared");

const viewerUrl = await sandbox.getPreviewViewerUrl("sandbox-id");
const preview = await sandbox.getPreviewConnection("sandbox-id");
await sandbox.startPreview("sandbox-id");
await sandbox.navigatePreview("sandbox-id", "https://example.com");
await sandbox.resizePreview("sandbox-id", \{ width: 1280, height: 800 \});
 
console.log(viewerUrl);   // Public standalone viewer page
console.log(preview?.wsUrl);

const cloud = new BrowserCloud(\{ apiKey: "br_live_..." \});
 
// Create a webhook
const webhook = await cloud.createWebhook(\{
  url: "https://your-app.com/webhooks/banata",
  eventTypes: ["session.ready", "session.ended", "sandbox.failed"],
\});
// webhook.signingSecret — save this to verify signatures
 
// List webhooks
const webhooks = await cloud.listWebhooks();
 
// Send a test delivery
await cloud.testWebhook(webhook.id);
 
// Delete a webhook
await cloud.deleteWebhook(webhook.id);

const cloud = new BrowserCloud(\{ apiKey: "br_live_..." \});
 
// Get current usage
const usage = await cloud.getUsage();
// usage.totalSessions, usage.totalBrowserHours
 
// Get billing info
const billing = await cloud.getBilling();
// billing.plan, billing.currentPeriod
 
// Create a checkout session for plan upgrade
const \{ checkoutUrl \} = await cloud.createCheckout(\{
  plan: "pro",
  successUrl: "https://your-app.com/billing/success",
\});

import \{ BrowserCloud, BanataSandbox, BanataError \} from "@banata-boxes/sdk";
 
try \{
  const session = await sandbox.launch(\{ runtime: "bun" \});
\} catch (error) \{
  if (error instanceof BanataError) \{
    console.log(error.status);        // HTTP status (e.g. 403)
    console.log(error.code);          // "PLAN_FEATURE_UNAVAILABLE"
    console.log(error.requiredPlan);  // "builder"
    console.log(error.currentPlan);   // "free"
    console.log(error.message);       // Human-readable message
  \}
\}

import puppeteer from "puppeteer-core";
import \{ BrowserCloud \} from "@banata-boxes/sdk";
 
const cloud = new BrowserCloud(\{ apiKey: process.env.BANATA_API_KEY! \});
 
const \{ cdpUrl, close \} = await cloud.launch(\{
  weight: "medium",
  stealth: true,
\});
 
const browser = await puppeteer.connect(\{ browserWSEndpoint: cdpUrl \});
const page = (await browser.pages())[0];
await page.goto("https://example.com");
console.log(await page.title());
 
await browser.disconnect();
await close();

import \{ BanataSandbox \} from "@banata-boxes/sdk";
 
const sandbox = new BanataSandbox(\{ apiKey: process.env.BANATA_API_KEY! \});
 
const session = await sandbox.launch(\{
  runtime: "python",
  size: "standard",
\});
 
// Write a Python script
await session.fs.write("/workspace/analyze.py", `
import json
data = \{"result": [i**2 for i in range(10)]\}
print(json.dumps(data))
`);
 
// Run it
const result = await session.exec("python3", ["/workspace/analyze.py"]);
console.log(JSON.parse(result.stdout));
 
await session.kill();

import \{ BanataSandbox \} from "@banata-boxes/sdk";
 
const sandbox = new BanataSandbox(\{ apiKey: process.env.BANATA_API_KEY! \});
 
const session = await sandbox.launch(\{
  runtime: "bun",
  capabilities: \{
    opencode: \{ enabled: true, defaultAgent: "build" \},
    browser: \{ mode: "paired-banata-browser", humanInLoop: true \},
  \},
\});
 
// Send AI agent a task
await session.prompt("Log into dashboard.example.com and export the monthly report");
 
// If the AI encounters MFA, request human help
await session.requestHumanHandoff(\{
  reason: "mfa",
  message: "MFA code needed for dashboard.example.com",
  resumePrompt: "Continue exporting the report after login",
\});
 
// ... human completes MFA via browser preview ...
 
await session.completeHumanHandoff(\{
  returnControlTo: "ai",
  runResumePrompt: true,
\});
 
await session.kill();