Introducing @runno/sandbox: A WebAssembly Sandbox for Running Code

@runno/sandbox is a simple package that gives you a secure WebAssembly-based sandbox for running code in various programming languages. It works in Node.js and other JavaScript runtimes, providing protection when running untrusted or potentially risky code.

tl;dr - it lets you run Python, Ruby, C++, and other languages inside JavaScript:

import { runCode } from "@runno/sandbox";

const result = await runCode(
  "ruby",
  "puts 'Hello JavaScript!'"
);

console.log("Ruby says:", result.stdout);

Which would output:

Ruby says: Hello JavaScript!

Why make a sandbox? Well, I had kind of already built one for the browser. My @runno/runtime package is a collection of Web Components for running code in the browser. It turns out it’s pretty easy to adapt browser JavaScript into something that runs from Node.

Because it was already built to use a Virtual File System, the Runno runtime makes for an excellent way to run untrusted code. The environment is fully isolated from your system resources, it has no access to your real files or network.

You could use it for running code generated by an LLM, or for testing code written by students, or for running customer functions on your own cloud.

In this post I’ll cover:

What you can do after installing @runno/sandbox (jump)
The architecture of Runno, and what makes it a secure sandbox (jump)
Limitations of the sandbox (jump)

What you can do after you `npm install @runno/sandbox`

The main thing you can do with @runno/sandbox is run code in various programming languages using either the runCode or runFS functions. The package supports these language runtimes:

python - CPython version 3.11.3 compiled by VMWare Labs
quickjs - WASMEdge’s QuickJS fork for JavaScript
clang - Clang fork for WASM by Binji
clangpp - Using the same Clang fork for C++
ruby - MRI Ruby version 3.2.0 compiled by VMWare Labs
php-cgi - PHP CGI version 8.2.0 compiled by VMWare Labs

Note: All these runtimes are packaged with Runno and run locally without connecting to the internet.

Using `runCode`

The runCode function lets you execute code snippets in any of the supported runtimes. Here’s its signature:

async function runCode(
  runtime: string,
  code: string,
  options?: {
    stdin?: string;
    timeout?: number;
  }
): Promise<RunResult>

Here are some examples:

Running a basic Python script

import { runCode } from "@runno/sandbox";

const result = await runCode(
  "python",
  'print("Hello from Python!")'
);
console.log(result.stdout); // "Hello from Python!"

Setting a timeout for long-running code

import { runCode } from "@runno/sandbox";

const code = "while (true);";  // Infinite loop

// 3 second timeout
const result = await runCode("quickjs", code, { timeout: 3 });

if (result.result_type === "timeout") {
  console.log("Execution timed out, as expected.");
} else {
  console.log("This shouldn't happen!");
}

Using `runFS` with a virtual filesystem

If your code needs to work with files, you can use the runFS function to provide a virtual filesystem:

import { runFS } from "@runno/sandbox";

const fs = {
  "/program.py": {
    path: "program.py",
    content: `
with open("data.txt", "r") as f:
  data = f.read()
  print(f"The file contains: {data}")
    `,
    mode: "string",
    timestamps: {
      access: new Date(),
      modification: new Date(),
      change: new Date(),
    },
  },
  "/data.txt": {
    path: "data.txt",
    content: "Hello from a file!",
    mode: "string",
    timestamps: {
      access: new Date(),
      modification: new Date(),
      change: new Date(),
    },
  },
};

const result = await runFS("python", "/program.py", fs);
console.log(result.stdout);

You can also access any files created or modified during execution via the result.fs field.

The architecture of Runno, and what makes it a secure sandbox

I do want to say up front that Runno is Open Source software with an MIT License, which specifically states:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND

I stand by that lack of a warranty. But I also think the sandbox is pretty good and I’d love to make it really good.

@runno/sandbox is built on WebAssembly technology, which provides several important security features:

Isolation: WebAssembly executes in a virtual environment separated from your system’s CPU and memory.
Memory safety: Code and data are kept separate, preventing dangerous operations like arbitrary code execution.
Controlled interfaces: The only way WebAssembly can interact with the outside world is through explicitly provided functions.

The sandbox is built on top of @runno/wasi, a WASI (WebAssembly System Interface) implementation. WASI provides a standardized way for WebAssembly modules to interact with the system. But this implementation is entirely virtual - it provides a file system that exists only in memory, with no access to your real file system.

The combination of WebAssembly’s inherent security properties and the controlled WASI implementation creates multiple layers of protection:

Code runs in a virtual machine (WebAssembly)
File operations happen in a virtual file system (in-memory)
No network access is provided
Execution time can be limited with timeouts

This makes @runno/sandbox a good solution for running untrusted code, especially code generated by LLMs.

Limitations of @runno/sandbox

To be transparent, there are some limitations to be aware of:

Package management: There’s currently no built-in package manager. If your code needs external libraries, you’ll need to provide them through the filesystem.
Limited capabilities: By design, the sandbox can’t access your network, real file system, or other system resources. This is a security feature, but it does limit what sandboxed code can do.
Performance: Running code through WebAssembly adds some overhead compared to native execution. For most use cases this isn’t noticeable, but it might matter for performance-critical applications.
Early release: This is a relatively new project and should be considered in its early stages. While it’s stable for many use cases, you might encounter edge cases or limitations.

Conclusion

@runno/sandbox provides a neat way to safely run code written in many languages. If you’re building AI-powered coding tools, educational platforms, or just need to evaluate user-provided code, it offers a secure environment that protects your system.

Try it out with:

npm install @runno/sandbox

I’d love to hear what you build with it!

What you can do after you npm install @runno/sandbox

Using runCode