Skip to main content

​
Installation

npm install @boxlite-ai/boxlite
Requirements:
  • Node.js 18 or later
  • Platform with hardware virtualization (see Prerequisites)
Verify Installation: 
import { SimpleBox } from '@boxlite-ai/boxlite';
console.log('BoxLite loaded successfully');

​
Basic Execution

1

Create a file hello.js

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

async function main() {
  const box = new SimpleBox({ image: 'python:slim' });
  try {
    const result = await box.exec('python', '-c', "print('Hello from BoxLite!')");
    console.log(result.stdout);
  } finally {
    await box.stop();
  }
}

main();
2

Run it

node hello.js
What’s happening:
  1. BoxLite pulls the python:slim OCI image (first run only)
  2. Creates a lightweight VM with the image
  3. Executes the Python command inside the VM
  4. Streams output back to your application
  5. Cleans up when stop() is called

​
TypeScript 5.2+ (Async Disposal)

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

async function main() {
  await using box = new SimpleBox({ image: 'alpine:latest' });
  const result = await box.exec('echo', 'Hello!');
  console.log(result.stdout);
  // Box automatically stopped when leaving scope
}

main();

​
Running Examples

BoxLite includes 5 Node.js examples:
1

Clone and build the SDK

# Clone the repository
git clone https://github.com/boxlite-labs/boxlite.git
cd boxlite/sdks/node

# Build the SDK
npm install && npm run build
npm link
2

Run the examples

cd ../../examples/node
npm link @boxlite-ai/boxlite

node simplebox.js
node codebox.js
node browserbox.js
node computerbox.js
node interactivebox.js
Examples overview:
#ExampleDescription
1simplebox.jsBasic command execution
2codebox.jsPython code execution sandbox
3browserbox.jsBrowser automation with CDP
4computerbox.jsDesktop automation (mouse, keyboard, screenshots)
5interactivebox.jsInteractive terminal sessions

​
Next Steps

Node.js SDK Reference

Complete API reference covering Core API (SimpleBox, CodeBox, BrowserBox, ComputerBox, InteractiveBox), TypeScript support and type definitions, Async disposal patterns (TypeScript 5.2+), and Error handling (ExecError, TimeoutError).