Skip to main content

​
Installation

npm install @boxlite-ai/boxlite
Requirements:
  • Node.js 18 or later
  • Platform with hardware virtualization (see Installation)
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();

​
Code Execution (AI Agents)

1

Create a file codebox.js

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

async function main() {
  const codebox = new CodeBox();
  try {
    // Execute untrusted code safely
    const code = `
import requests
response = requests.get('https://api.github.com/zen')
print(response.text)
`;
    const result = await codebox.run(code);
    console.log(result);
  } finally {
    await codebox.stop();
  }
}

main();
2

Run it

node codebox.js
What’s happening:
  1. CodeBox automatically installs required packages (requests)
  2. Executes the code in complete isolation
  3. Returns the output as a string
  4. Your host system remains completely safe

​
Running Examples

BoxLite includes 5 Node.js examples:
1

Clone and build the SDK

# Clone the repository
git clone https://github.com/boxlite-ai/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

Core concepts

Understand the different box types (SimpleBox, CodeBox, BrowserBox, and more), lifecycle, images, and resource configuration.

Execute AI-generated code

Learn to use CodeBox for safe code execution — auto-install packages, run untrusted code, and capture output.

Node.js SDK Reference

Complete API reference for SimpleBox, CodeBox, BrowserBox, ComputerBox, and more.