> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Box Types

> Node.js SDK box types and configuration

BoxLite provides several specialized box types, each tailored for a specific use case. All box types share a common foundation built on the low-level `JsBox` handle.

***

## Box Handle

### `JsBox`

Handle to a running or stopped box.

#### Properties

| Property | Type             | Description                  |
| -------- | ---------------- | ---------------------------- |
| `id`     | `string`         | Unique box identifier (ULID) |
| `name`   | `string \| null` | User-defined name            |

#### Methods

| Method      | Signature                                          | Description             |
| ----------- | -------------------------------------------------- | ----------------------- |
| `info()`    | `() => JsBoxInfo`                                  | Get box metadata (sync) |
| `exec()`    | `(cmd, args?, env?, tty?) => Promise<JsExecution>` | Execute command         |
| `stop()`    | `() => Promise<void>`                              | Stop the box            |
| `metrics()` | `() => Promise<JsBoxMetrics>`                      | Get resource metrics    |

***

### `JsBoxInfo`

Metadata about a box.

| Field         | Type                  | Description                                                  |
| ------------- | --------------------- | ------------------------------------------------------------ |
| `id`          | `string`              | Unique box identifier (ULID)                                 |
| `name`        | `string \| undefined` | User-defined name                                            |
| `status`      | `string`              | Current status: `"Starting"`, `"Running"`, `"Stopped"`, etc. |
| `createdAt`   | `string`              | Creation timestamp (ISO 8601)                                |
| `lastUpdated` | `string`              | Last state change (ISO 8601)                                 |
| `pid`         | `number \| undefined` | Process ID (if running)                                      |

***

### `BoxStatus`

A box can be in one of the following states:

| Status       | Description                          |
| ------------ | ------------------------------------ |
| `"Starting"` | Box is being initialized             |
| `"Running"`  | Box is active and accepting commands |
| `"Stopped"`  | Box has been stopped                 |

***

## SimpleBox

Context manager for basic command execution with automatic cleanup.

```typescript theme={null}
import { SimpleBox } from '@boxlite-ai/boxlite';
```

### Constructor Options

```typescript theme={null}
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
}
```

### Properties

| Property | Type                  | Description                    |
| -------- | --------------------- | ------------------------------ |
| `id`     | `string`              | Box ID (throws if not started) |
| `name`   | `string \| undefined` | Box name                       |

### Methods

| Method                    | Signature                               | Description          |
| ------------------------- | --------------------------------------- | -------------------- |
| `getId()`                 | `() => Promise<string>`                 | Get box ID (async)   |
| `getInfo()`               | `() => Promise<JsBoxInfo>`              | Get box info (async) |
| `exec()`                  | `(cmd, ...args) => Promise<ExecResult>` | Execute and wait     |
| `stop()`                  | `() => Promise<void>`                   | Stop the box         |
| `[Symbol.asyncDispose]()` | `() => Promise<void>`                   | Async disposal       |

### Example

```typescript theme={null}
// 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();
}
```

***

## CodeBox

Python code execution sandbox.

```typescript theme={null}
import { CodeBox } from '@boxlite-ai/boxlite';
```

### Constructor Options

```typescript theme={null}
interface CodeBoxOptions extends SimpleBoxOptions {
  image?: string;  // Default: "python:slim"
}
```

### Methods

| Method              | Signature                                 | Description         |
| ------------------- | ----------------------------------------- | ------------------- |
| `run()`             | `(code: string) => Promise<string>`       | Execute Python code |
| `runScript()`       | `(scriptPath: string) => Promise<string>` | Run script file     |
| `installPackage()`  | `(pkg: string) => Promise<string>`        | pip install         |
| `installPackages()` | `(...pkgs: string[]) => Promise<string>`  | Install multiple    |

### Example

```typescript theme={null}
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();
}
```

***

## BrowserBox

Browser automation with Chrome DevTools Protocol.

```typescript theme={null}
import { BrowserBox, BrowserType } from '@boxlite-ai/boxlite';
```

### Constructor Options

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

### `BrowserType`

Supported browser types.

```typescript theme={null}
type BrowserType = 'chromium' | 'firefox' | 'webkit';
```

### Default image

All browser types use a single Playwright image: `mcr.microsoft.com/playwright:v1.58.0-jammy`

The Playwright Server listens on port **3000**. The CDP endpoint (for Puppeteer) is on port **9222**.

### Properties

| Property  | Type          | Description                                                 |
| --------- | ------------- | ----------------------------------------------------------- |
| `browser` | `BrowserType` | The browser type (`'chromium'`, `'firefox'`, or `'webkit'`) |

### Methods

| Method                 | Signature                                              | Description                                                                             |
| ---------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `start()`              | `(timeout?: number) => Promise<void>`                  | Start browser                                                                           |
| `endpoint()`           | `(timeout?: number) => Promise<string>`                | Get CDP endpoint URL (for Puppeteer)                                                    |
| `playwrightEndpoint()` | `(timeout?: number) => Promise<string>`                | Get WebSocket endpoint URL (for Playwright)                                             |
| `connect()`            | `(options?: { timeout?: number }) => Promise<Browser>` | Connect and return a Playwright Browser instance. Requires `playwright-core` installed. |

### Example

```typescript theme={null}
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();
}
```

***

## ComputerBox

Desktop automation with full GUI environment. Uses the `lscr.io/linuxserver/webtop:ubuntu-xfce` image by default.

```typescript theme={null}
import { ComputerBox } from '@boxlite-ai/boxlite';
```

### Constructor Options

```typescript theme={null}
interface ComputerBoxOptions {
  cpus?: number;          // Default: 2
  memoryMib?: number;     // Default: 2048
  guiHttpPort?: number;   // Default: 3000
  guiHttpsPort?: number;  // Default: 3001
}
```

### Mouse Methods

| Method             | Signature                                       | Description    |
| ------------------ | ----------------------------------------------- | -------------- |
| `mouseMove()`      | `(x: number, y: number) => Promise<void>`       | Move cursor    |
| `leftClick()`      | `() => Promise<void>`                           | Left click     |
| `rightClick()`     | `() => Promise<void>`                           | Right click    |
| `middleClick()`    | `() => Promise<void>`                           | Middle click   |
| `doubleClick()`    | `() => Promise<void>`                           | Double click   |
| `tripleClick()`    | `() => Promise<void>`                           | Triple click   |
| `leftClickDrag()`  | `(startX, startY, endX, endY) => Promise<void>` | Drag           |
| `cursorPosition()` | `() => Promise<[number, number]>`               | Get cursor pos |

### Keyboard Methods

| Method   | Signature                                | Description  |
| -------- | ---------------------------------------- | ------------ |
| `type()` | `(text: string) => Promise<void>`        | Type text    |
| `key()`  | `(keySequence: string) => Promise<void>` | Press key(s) |

#### Key Syntax Reference (xdotool format)

| Key           | Syntax                                |
| ------------- | ------------------------------------- |
| Enter         | `Return`                              |
| Tab           | `Tab`                                 |
| Escape        | `Escape`                              |
| Backspace     | `BackSpace`                           |
| Delete        | `Delete`                              |
| Space         | `space`                               |
| Arrow keys    | `Up`, `Down`, `Left`, `Right`         |
| Function keys | `F1`, `F2`, ... `F12`                 |
| Page keys     | `Page_Up`, `Page_Down`, `Home`, `End` |
| Modifiers     | `ctrl`, `alt`, `shift`, `super`       |
| Combinations  | `ctrl+c`, `ctrl+shift+s`, `alt+Tab`   |

**Examples:**

```typescript theme={null}
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
```

### Display Methods

| Method             | Signature                                     | Description      |
| ------------------ | --------------------------------------------- | ---------------- |
| `waitUntilReady()` | `(timeout?: number) => Promise<void>`         | Wait for desktop |
| `screenshot()`     | `() => Promise<Screenshot>`                   | Capture screen   |
| `scroll()`         | `(x, y, direction, amount?) => Promise<void>` | Scroll           |
| `getScreenSize()`  | `() => Promise<[number, number]>`             | Get dimensions   |

#### Screenshot Return Type

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

#### Scroll Directions

| Direction | Description  |
| --------- | ------------ |
| `"up"`    | Scroll up    |
| `"down"`  | Scroll down  |
| `"left"`  | Scroll left  |
| `"right"` | Scroll right |

### Example

```typescript theme={null}
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();
}
```

***

## InteractiveBox

Interactive terminal sessions with PTY support.

```typescript theme={null}
import { InteractiveBox } from '@boxlite-ai/boxlite';
```

### Constructor Options

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

#### TTY Mode

| Value       | Behavior                      |
| ----------- | ----------------------------- |
| `undefined` | Auto-detect from stdin        |
| `true`      | Force TTY with I/O forwarding |
| `false`     | No I/O forwarding             |

### Methods

| Method    | Signature             | Description         |
| --------- | --------------------- | ------------------- |
| `start()` | `() => Promise<void>` | Start PTY session   |
| `wait()`  | `() => Promise<void>` | Wait for shell exit |

### Example

```typescript theme={null}
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();
}
```