Node.js SDK reference

# Core SDK
npm install @boxlite-ai/boxlite
# Required only when connecting to a remote browser via BrowserBox
npm install playwright-core

// quickstart.mjs  —  run: node quickstart.mjs
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  // Box is created lazily: the image is pulled and the micro-VM started only on the first exec()
  const box = new SimpleBox({ image: "alpine:latest" });
  try {
    const result = await box.exec("echo", "Hello from BoxLite!");

    // Note: a non-zero exit code does not raise; check exitCode yourself
    if (result.exitCode !== 0) {
      console.error("command failed:", result.stderr);
    } else {
      console.log("stdout:", result.stdout.trim());
    }
  } catch (err) {
    // Startup failures (no virtualization, image pull failure, etc.) are thrown here
    console.error("Box runtime error:", err instanceof Error ? err.message : err);
  } finally {
    await box.stop(); // autoRemove defaults to true; stopping cleans up
  }
}

main();

// Requires Node >= 20 and tsconfig target >= ES2022 / explicit resource management enabled
import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  try {
    await using box = new SimpleBox({ image: "alpine:latest" });
    const result = await box.exec("uname", "-a");
    console.log(result.stdout.trim());
  } catch (err) {
    console.error("error:", err instanceof Error ? err.message : err);
  }
  // Automatically stops and cleans up on scope exit
}

main();

import {
  // Wrapper-layer Box types (recommended entry points)
  SimpleBox, CodeBox, BrowserBox, ComputerBox, InteractiveBox, SkillBox,
  // Runtime and REST
  JsBoxlite, BoxliteRestOptions, ApiKeyCredential,
  // Error types
  BoxliteError, ExecError, TimeoutError, ParseError,
  // Low-level access
  getJsBoxlite, getNativeModule,
} from "@boxlite-ai/boxlite";

// Constants (DEFAULT_CPUS, SKILLBOX_IMAGE, etc.) are exposed via export *
import { DEFAULT_CPUS, DEFAULT_MEMORY_MIB } from "@boxlite-ai/boxlite";

interface ExecResult {
  exitCode: number; // 0 = success; a non-zero code does not raise, check it yourself
  stdout: string;
  stderr: string;
}

import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  const box = new SimpleBox({ image: "alpine:latest" });
  try {
    // exec(cmd, args[], env, options)
    const r1 = await box.exec("pwd", [], undefined, { cwd: "/tmp" });
    console.log("cwd:", r1.stdout.trim());

    // Inject environment variables (env is an object, not an array)
    const r2 = await box.exec("env", [], { FOO: "bar" });
    console.log(r2.stdout);

    // Per-command timeout (seconds)
    const r3 = await box.exec("sleep", ["60"], undefined, { timeoutSecs: 5 });
    console.log("exit:", r3.exitCode);
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await box.stop();
  }
}

main();

import { CodeBox } from "@boxlite-ai/boxlite";

async function main() {
  const codebox = new CodeBox({ memoryMib: 1024 });
  try {
    await codebox.installPackage("requests");
    const out = await codebox.run(
      "import requests; print(requests.get('https://api.github.com/zen').text)"
    );
    console.log(out);
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await codebox.stop();
  }
}

main();

// Requires: npm install playwright-core
import { BrowserBox } from "@boxlite-ai/boxlite";
import { chromium } from "playwright-core";

async function main() {
  const box = new BrowserBox({ browser: "chromium" });
  try {
    const ws = await box.playwrightEndpoint(); // returns a ws:// endpoint
    const browser = await chromium.connect(ws);
    const page = await browser.newPage();
    await page.goto("https://example.com");
    console.log(await page.title());
    await browser.close();
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await box.stop();
  }
}

main();

import { ComputerBox } from "@boxlite-ai/boxlite";

async function main() {
  const desktop = new ComputerBox({ cpus: 4, memoryMib: 4096 });
  try {
    await desktop.waitUntilReady(60);
    const shot = await desktop.screenshot();
    console.log(`screen: ${shot.width}x${shot.height}`);
    await desktop.mouseMove(100, 200);
    await desktop.leftClick();
    await desktop.type("Hello, World!");
    await desktop.key("Return");
    // Open http://localhost:3000 in a browser to view the live desktop
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await desktop.stop();
  }
}

main();

interface SecurityOptions {
  jailerEnabled?: boolean;
  seccompEnabled?: boolean;
  maxOpenFiles?: number;
  maxFileSize?: number;
  maxProcesses?: number;
  maxMemory?: number;
  maxCpuTime?: number;
  networkEnabled?: boolean;
  closeFds?: boolean;
}

import { SimpleBox } from "@boxlite-ai/boxlite";

async function main() {
  const box = new SimpleBox({
    image: "alpine:latest",
    volumes: [
      { hostPath: "<YOUR_HOST_PATH>", guestPath: "/data", readOnly: true }, // read-only
    ],
    ports: [{ hostPort: 8080, guestPort: 80 }],
    network: { mode: "enabled", allowNet: ["example.com"] },
    secrets: [
      { name: "API_KEY", value: "<YOUR_API_KEY>", hosts: ["api.example.com"] },
    ],
  });
  try {
    const r = await box.exec("ls", "/data");
    console.log(r.stdout);
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await box.stop();
  }
}

main();

import { JsBoxlite } from "@boxlite-ai/boxlite";

async function main() {
  const runtime = JsBoxlite.withDefaultConfig();
  const box = await runtime.create({ image: "alpine:latest" });
  try {
    const execution = await box.exec("sh", ["-c", "echo line1; echo line2"]);

    // A stream can be consumed only once; iterate to EOF
    const stdout = await execution.stdout();
    while (true) {
      const line = await stdout.next();
      if (line === null) break; // EOF
      console.log(line);
    }

    const result = await execution.wait();
    console.log("exit code:", result.exitCode);
  } catch (err) {
    console.error(err instanceof Error ? err.message : err);
  } finally {
    await box.stop();
    runtime.close();
  }
}

main();

const execution = await box.exec("cat", []);
const stdin = await execution.stdin();
await stdin.writeString("hello\n");
await stdin.write(Buffer.from([10])); // a newline byte
await stdin.close();                  // signal EOF so cat returns
const result = await execution.wait();

import { JsBoxlite } from "@boxlite-ai/boxlite";

async function main() {
  const runtime = JsBoxlite.withDefaultConfig();

  const pulled = await runtime.images.pull("alpine:latest");
  console.log(pulled.reference, pulled.configDigest, pulled.layerCount);

  const images = await runtime.images.list();
  for (const image of images) {
    console.log(image.repository, image.tag, image.id);
  }
  runtime.close();
}

main();

import { ApiKeyCredential, BoxliteRestOptions, JsBoxlite } from "@boxlite-ai/boxlite";

const rt = JsBoxlite.rest(
  new BoxliteRestOptions({
    url: "http://localhost:8100",
    credential: new ApiKeyCredential("<YOUR_API_KEY>"), // TODO: replace
  }),
);
const boxes = await rt.listInfo();

// Env discovery -- returns null when BOXLITE_API_KEY is unset:
const cred = ApiKeyCredential.fromEnv();
const rt2 = JsBoxlite.rest(new BoxliteRestOptions({ url: "http://localhost:8100", credential: cred ?? undefined }));

import { JsBoxlite, BoxliteRestOptions, ApiKeyCredential } from "@boxlite-ai/boxlite";

const rt = JsBoxlite.rest(new BoxliteRestOptions({
  url: "https://api.boxlite.ai",
  credential: new ApiKeyCredential("<YOUR_API_KEY>"), // TODO: replace
  pathPrefix: "acme",   // -> requests hit /v1/acme/boxes
}));

Error: Cannot find module 'boxlite'

SyntaxError: Cannot use import statement outside a module

Error: Failed to convert napi value into rust type `bool` on JsVolumeSpec.readOnly on JsBoxOptions.volumes

try {
  await box.exec("this-command-does-not-exist");
} catch (err) {
  // May be an ExecError/TimeoutError, or a bare Error
  console.error("execution error:", err instanceof Error ? err.message : String(err));
}

Error: Box not yet created. Call exec() first or use getId() async method.

// Wrong
import { SimpleBox } from "boxlite"; // does not exist
// Correct
import { SimpleBox } from "@boxlite-ai/boxlite";