Stonebox

Stonebox is a powerful TypeScript library for running sandboxed code locally. It provides a simple, modern API for executing JavaScript, TypeScript, and Python within secure, isolated environments.

Stonebox is designed for reliability and developer experience. It uses a clean, environment-based factory pattern and supports both lightweight process-based sandboxing and high-security Docker container isolation.

This is the core, open-source engine that will power the Stonebox Cloud platform.

Key Features

• Isolated Environments: Create sandboxes with their own file systems on the fly.
• Multi-Language Support: Execute JavaScript, TypeScript, and Python code seamlessly.
• Secure by Default: Leverage Docker for strong, OS-level isolation of untrusted code.
• Flexible Execution: Run any command within the sandboxed environment.
• Resource Management: Control execution time with timeouts and memory limits.
• Simple, Modern API: A declarative, async/await first API that is a pleasure to use.
• Extensible: A clean engine architecture ready for future language and runtime support.

Installation

npm install @plust/stonebox

Quick Start: Python in Docker

Here is how simple it is to securely run a Python script inside a locked-down Docker container.

import { Stonebox } from '@plust/stonebox';

async function main() {
  const stonebox = new Stonebox();
  let environment;

  try {
    // 1. Create a secure, isolated environment
    environment = await stonebox.createEnvironment({
      language: 'python',
      engineType: 'docker',
      dockerEngineOptions: {
        image: 'python:3.10-slim',
        networkMode: 'none', // Disable network access
        workspaceMountMode: 'ro', // Mount code as read-only
      },
      timeoutMs: 5000,
    });

    // 2. Add files to the environment's virtual filesystem
    await environment.addFile(
      'main.py',
      'import os; print(f"Hello from Python! Current dir: {os.getcwd()}")'
    );

    // 3. Execute a command within the environment
    console.log('Executing script in Docker...');
    const result = await environment.execute('python3', ['main.py']);

    // 4. Use the results
    console.log('--- Execution Result ---');
    console.log('STDOUT:', result.stdout.trim());
    console.log('STDERR:', result.stderr.trim());
    console.log('Exit Code:', result.exitCode);
    console.log('Duration:', `${result.durationMs}ms`);

  } catch (error) {
    console.error('An error occurred:', error);
  } finally {
    // 5. Clean up the environment and its temporary files
    if (environment) {
      console.log('Deleting environment...');
      await environment.delete();
    }
  }
}

main();

API Reference

The Stonebox API is designed around two core concepts: a stateless Stonebox factory and stateful ExecutionEnvironment instances.

The Stonebox Factory

This is your main entry point.

import { Stonebox } from '@plust/stonebox';
const stonebox = new Stonebox();

• createEnvironment(options: EnvironmentOptions): Promise<ExecutionEnvironment> Creates and returns a new sandboxed environment. This sets up a temporary directory on the host machine.

The ExecutionEnvironment

This object represents a single, active sandbox.

• addFile(path: string, content: string): Promise<void> Adds a file to the environment's filesystem.
• addFiles(files: Array<{ path, content }>): Promise<void> A convenience method to add multiple files at once.
• execute(command: string, args?: string[], options?: ExecuteOptions): Promise<ExecutionResult> Executes a shell command inside the environment. This is the primary method for running code.
• delete(): Promise<void> Destroys the environment, permanently deleting its temporary directory and all contained files.

Core Interfaces

EnvironmentOptions

Options for creating a new environment.

Option	Type	Description
language	'javascript' | ...	Required. The primary language for the environment.
engineType	'process' | 'docker'	The execution engine. Defaults to 'process'.
dockerEngineOptions	DockerEngineSpecificOptions	Required options when engineType is 'docker'.
timeoutMs	number	Default execution timeout for all commands.
memoryLimitMb	number	Default memory limit.
env	Record<string, string>	Default environment variables.
languageOptions	StoneboxLanguageOptions	Language-specific settings (e.g., pythonPath).

ExecuteOptions

Options for a single execute call, which override any defaults from EnvironmentOptions.

Option	Type	Description
timeoutMs	number	Override the default timeout.
memoryLimitMb	number	Override the default memory limit.
env	Record<string, string>	Override or extend environment variables.

ExecutionResult

Property	Type	Description
stdout	string	The captured standard output.
stderr	string	The captured standard error.
exitCode	number	The exit code of the process.
durationMs	number	The total execution time in milliseconds.
signal	string	The signal that terminated the process, if any.

Security with Docker

For executing untrusted code, always use engineType: 'docker'. The dockerEngineOptions give you fine-grained control over the container's security policy. Best practices include:

• networkMode: 'none': Completely disables all network access.
• workspaceMountMode: 'ro': Prevents the running code from modifying its own source files.
• capDrop: 'ALL': Drops all Linux kernel capabilities for a minimal-privilege environment.
• noNewPrivileges: true: Prevents the process from escalating its privileges.

const secureOpts = {
  engineType: 'docker',
  dockerEngineOptions: {
    image: 'node:18-slim',
    networkMode: 'none',
    workspaceMountMode: 'ro',
    capDrop: 'ALL',
    noNewPrivileges: true,
  }
};