sandboxjs

A unified interface for Linux-based cloud sandbox providers. It can be used to create the building blocks of AI agents that run code or perform other potentially unsafe operations.

Usage

import Sandbox from "@jamesmurdza/sandboxjs";

// Create a new sandbox
const sandbox = await Sandbox.create("daytona"); // or "codesandbox" or "e2b"

// Connect to an existing sandbox
// const sandbox = await Sandbox.connect("daytona", "sandbox_id");

// Run commands and interact with the sandbox
console.log(await sandbox.runCommand("echo 'hello world'"));
console.log(await sandbox.listFiles("/"));

// Suspend, resume and destroy the sandbox
await sandbox.suspend();
await sandbox.resume();
await sandbox.destroy();

Provider Support

| Provider | File Persistence | Memory Persistence | Read/Write Files | Recursive Delete | Directory Watch | Preview URLs | Pseudo-terminals | Destroy Sandbox | | --------------- | ---------------- | ------------------ | ---------------- | ---------------- | --------------- | ------------ | ---------------- | --------------- | | E2B | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Daytona | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | | CodeSandbox | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |

Getting Started

1. Set up environment variables

Create a .env file in the root directory of the project and add at least one of the following environment variables:

# Get an E2B API key here: https://e2b.dev/dashboard
E2B_API_KEY=
# Get a Daytona API key here: https://app.daytona.io/dashboard/keys
DAYTONA_API_KEY=
# Get a CodeSandbox API key here: https://codesandbox.io/t
CODESANDBOX_API_KEY=

2. Install dependencies

npm install

3. Build the project

Compiles the TypeScript source files to JavaScript in the dist/ directory.

npm run build

4. Run the example

After building, run the example script:

node dist/example.js

5. Run tests

To run the test suite:

npm test

Methods

create

const sandbox = await Sandbox.create("daytona"); // or "codesandbox" or "e2b"

connect

const sandbox = await Sandbox.connect("daytona", "sandbox_id");

runCommand

console.log(await sandbox.runCommand("echo 'hello world'"));

suspend

await sandbox.suspend();

resume

await sandbox.resume();

destroy

await sandbox.destroy();

readFile

console.log(await sandbox.readFile("/path/to/file"));

writeFile

await sandbox.writeFile("/path/to/file", "content");

listFiles

console.log(await sandbox.listFiles("/path/to/directory"));

moveFile

await sandbox.moveFile("/path/to/file", "/path/to/new/file");

deleteFile

await sandbox.deleteFile("/path/to/file");

createDirectory

await sandbox.createDirectory("/path/to/directory");

getPreviewUrl

console.log(await sandbox.getPreviewUrl(8080));

createTerminal

const terminal = await sandbox.createTerminal();

Terminal Methods

await terminal.write("echo 'hello world'");
await terminal.resize(80, 24);
await terminal.kill();

Future Plans

• Add support for watching file system changes
• Add pseudo-terminal support
• Add support for running commands in the background