Box Types

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

interface SimpleBoxOptions {
  image?: string;         // Default: "python:slim"
  rootfsPath?: string;    // Local OCI layout directory (alternative to image)
  memoryMib?: number;     // Memory in MiB
  cpus?: number;          // CPU cores
  diskSizeGb?: number;    // Persistent disk size in GB
  runtime?: JsBoxlite;    // Runtime instance
  name?: string;          // Box name
  autoRemove?: boolean;   // Default: true
  reuseExisting?: boolean; // Default: false — reuse existing box with same name
  detach?: boolean;       // Default: false
  workingDir?: string;    // Working directory
  env?: Record<string, string>;  // Environment variables
  volumes?: VolumeSpec[]; // Volume mounts
  ports?: PortSpec[];     // Port mappings
  entrypoint?: string[];  // Override image entrypoint
  cmd?: string[];         // Override image CMD
  user?: string;          // Run as specific user
}

// With async disposal (TypeScript 5.2+)
await using box = new SimpleBox({ image: 'alpine:latest' });
const result = await box.exec('echo', 'Hello!');
console.log(result.stdout);

// Manual cleanup
const box = new SimpleBox({ image: 'alpine:latest' });
try {
  const result = await box.exec('ls', '-la');
  console.log(result.stdout);
} finally {
  await box.stop();
}

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

interface CodeBoxOptions extends SimpleBoxOptions {
  image?: string;  // Default: "python:slim"
}

const codebox = new CodeBox({ memoryMib: 1024 });
try {
  await codebox.installPackage('requests');
  const result = await codebox.run(`
import requests
print(requests.get('https://api.github.com/zen').text)
  `);
  console.log(result);
} finally {
  await codebox.stop();
}

import { BrowserBox, BrowserType } from '@boxlite-ai/boxlite';

interface BrowserBoxOptions {
  browser?: BrowserType;  // "chromium" | "firefox" | "webkit"
  memoryMib?: number;     // Default: 2048
  cpus?: number;          // Default: 2
}

type BrowserType = 'chromium' | 'firefox' | 'webkit';

import { BrowserBox } from '@boxlite-ai/boxlite';

const browser = new BrowserBox({ browser: 'chromium' });
try {
  // Option 1: Use with Playwright (recommended)
  const pw = await browser.connect();
  const page = await pw.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  // Option 2: Get endpoints manually
  const ws = await browser.playwrightEndpoint();  // "ws://localhost:3000/"
  const cdp = await browser.endpoint();           // "ws://localhost:3000/..."
} finally {
  await browser.stop();
}

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

interface ComputerBoxOptions {
  cpus?: number;          // Default: 2
  memoryMib?: number;     // Default: 2048
  guiHttpPort?: number;   // Default: 3000
  guiHttpsPort?: number;  // Default: 3001
}

await desktop.key('Return');        // Press Enter
await desktop.key('ctrl+c');        // Copy
await desktop.key('ctrl+shift+s');  // Save As
await desktop.key('alt+Tab');       // Switch window
await desktop.key('ctrl+a Delete'); // Select all and delete

interface Screenshot {
  data: string;    // Base64-encoded PNG
  width: number;   // 1024 (default)
  height: number;  // 768 (default)
  format: 'png';
}

const desktop = new ComputerBox({ cpus: 4, memoryMib: 4096 });
try {
  await desktop.waitUntilReady(60);

  // Take screenshot
  const screenshot = await desktop.screenshot();
  console.log(`${screenshot.width}x${screenshot.height}`);

  // GUI interaction
  await desktop.mouseMove(100, 200);
  await desktop.leftClick();
  await desktop.type('Hello, World!');
  await desktop.key('Return');

  // Access via browser: http://localhost:3000
} finally {
  await desktop.stop();
}

import { InteractiveBox } from '@boxlite-ai/boxlite';

interface InteractiveBoxOptions extends SimpleBoxOptions {
  shell?: string;        // Default: "/bin/sh"
  tty?: boolean;         // undefined = auto-detect
}

const box = new InteractiveBox({
  image: 'alpine:latest',
  shell: '/bin/sh',
  tty: true
});
try {
  await box.start();
  await box.wait();  // Blocks until shell exits
} finally {
  await box.stop();
}