Microsandbox JavaScript/TypeScript SDK

A secure, efficient sandbox for executing untrusted code from TypeScript/JavaScript applications.

Installation

npm install microsandbox

Requirements

• Node.js 14.x or later
• A running Microsandbox server with a valid API key

Configuration

Before using the SDK, you need to set your Microsandbox API key:

export MSB_API_KEY=msb_***

Quick Start

Here's a simple example using the NodeSandbox to execute JavaScript code:

import { NodeSandbox } from "microsandbox";

async function main() {
  // Create and start a Node.js sandbox
  const sb = await NodeSandbox.create({ name: "test" });

  try {
    // Execute JavaScript code in the sandbox
    let exec = await sb.run("var name = 'JavaScript'");
    exec = await sb.run("console.log(`Hello ${name}!`)");

    // Get the output
    console.log(await exec.output()); // prints Hello JavaScript!
  } finally {
    // Stop the sandbox when done
    await sb.stop();
  }
}

main().catch(console.error);

Available Sandbox Types

The SDK provides several specialized sandbox environments:

• NodeSandbox: For executing JavaScript/TypeScript code
• PythonSandbox: For executing Python code

Each sandbox type is optimized for its respective language environment.

Creating a Sandbox

You can create a sandbox with custom options:

import { NodeSandbox, SandboxOptions } from "microsandbox";

// Using builder pattern
const options = SandboxOptions.builder()
  .name("my-sandbox")
  .memory(1024)
  .cpus(2)
  .build();

// Create and start the sandbox
const sandbox = await NodeSandbox.create(options);

// Don't forget to stop the sandbox when done
await sandbox.stop();

Running Shell Commands

You can execute shell commands in the sandbox:

const cmd = await sandbox.command.run("ls", ["-la"]);
console.log(await cmd.output());
console.log("Exit code:", cmd.exitCode);

Monitoring Sandbox Metrics

Get resource usage metrics for your sandbox:

// Get all metrics
const metrics = await sandbox.metrics.all();
console.log(metrics);

// Get specific metrics
const cpuUsage = await sandbox.metrics.cpu();
const memoryUsage = await sandbox.metrics.memory();
const diskUsage = await sandbox.metrics.disk();

Error Handling

try {
  const exec = await sandbox.run("invalid code");

  if (exec.hasError()) {
    console.error("Execution error:", await exec.error());
  } else {
    console.log("Result:", await exec.output());
  }
} catch (err) {
  console.error("Sandbox error:", err.message);
}

Development

Building the SDK

npm run build

Running Tests

npm test

License

Apache License 2.0