Runno

🚀 Runno

Runno is a collection of JavaScript packages that enables code execution in various languages within a sandbox, offering a convenient and secure solution for running code examples.

👨‍💻 Use Runno 👉 Runno.dev

📖 Documentation 👉 Runno.dev

🚀 Quick Start

Runno consists of multiple JavaScript Packages designed to execute code in diverse languages within a sandbox. Here's a quick overview of its components:

• @runno/runtime - Web components and headless tools for running code examples in the browser.
• @runno/sandbox - A secure sandbox for running code examples in Node and other JS Runtimes.
• @runno/wasi - An isomorphic package for running WebAssembly WASI binaries inside a sandbox.
• @runno/mcp - An MCP Server for running code using the @runno/sandbox package.

There's also a deprecated Python package named runno, which functions similarly to the sandbox package.

This project is powered by WASI, the Web Assembly System Interface. It offers a standard way for programs to interact with an operating system. By emulating this interface, we can provide a fake file system and operating system, all running within JavaScript.

✨ Features

Using @runno/runtime

The @runno/runtime package provides Web Components for running code in the browser, which is extremely useful for programming education:

• Newbies don't need to install complex programming tools to run code.
• Programming examples can be made runnable in the browser without a server.
• Simple programs can be tested for correctness inside a sandbox on the user's machine.

Quickstart

1. Add @runno/runtime to your package:

npm install @runno/runtime

2. Import @runno/runtime where you'll use the runno elements. The simplest way is in your entrypoint file (e.g., main.ts or index.ts).

import "@runno/runtime";

3. Use runno elements on the page:

<runno-run runtime="python" editor controls> print('Hello, World!') </runno-run>

4. To make the code run, set the following HTTP headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

These headers create a cross-origin isolated context, allowing the use of SharedArrayBuffer for implementing STDIN.

Supported Runtimes

The system supports several runtimes based on existing packages published to WAPM. These runtimes are associated with Runno and will be supported in the future:

• python - Runs python3 code, with a minimum version of at least 3.6.
• ruby - Runs standard Ruby, with a minimum version of at least 3.2.0.
• quickjs - Runs JavaScript code using the QuickJS engine.
• sqlite - Runs SQLite commands.
• clang - Compiles and runs C code.
• clangpp - Compiles and runs C++ code.
• php-cgi - Runs PHP CGI compiled by VMWare.

Running WASI binaries

The runtime also provides a component for directly running WASI binaries:

<runno-wasi src="/ffmpeg.wasm" autorun></runno-wasi>

Examples

More examples of using Runno can be found in the examples directory of this repository. It includes practical usage scenarios and configuration instructions.

Full documentation

Visit @runno/runtime to read the full documentation.

How does it work?

Runno uses Web Assembly to execute code from JavaScript. The code runs in a Unix-like sandbox connected to a web-based terminal emulator, behaving similarly to running code natively on a Linux terminal. Although it's not perfect, it's very useful for running code examples.

Using @runno/sandbox

Quickstart

1. Install the sandbox:

npm install @runno/sandbox

2. Use it to run code:

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

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

if (result.resultType === "complete") {
  console.log(result.stdout);
} else {
  console.log("Oh no!");
}

You can also perform more complex operations, such as running against a virtual file system using runFS:

function runFS(
  runtime: Runtime,
  entryPath: string,
  fs: WASIFS,
  options?: {
    stdin?: string;
    timeout?: number;
  },
): Promise<RunResult>;

Using @runno/wasi

Quickstart

The quickest way to start with Runno is by using the WASI.start class method. It will set up everything you need and directly run the Wasm binary. Note that this will run on the main thread, not inside a worker, so it will interrupt any interactive use of the browser until it completes.

import { WASI } from "@runno/wasi";

//...

const result = WASI.start(fetch("/binary.wasm"), {
  args: ["binary-name", "--do-something", "some-file.txt"],
  env: { SOME_KEY: "some value" },
  stdout: (out) => console.log("stdout", out),
  stderr: (err) => console.error("stderr", err),
  stdin: () => prompt("stdin:"),
  fs: {
    "/some-file.txt": {
      path: "/some-file.txt",
      timestamps: {
        access: new Date(),
        change: new Date(),
        modification: new Date(),
      },
      mode: "string",
      content: "Some content for the file.",
    },
  },
});

A more complete example can be found in src/main.ts.

Note: The args should start with the name of the binary, just like when you run a terminal command (e.g., cat somefile, where the binary name is cat).

Full documentation

Visit @runno/wasi to read the full documentation, including instructions for running inside a worker and how the virtual file system works.

Using @runno/mcp

Quickstart

Depending on your MCP server configuration, you can add Runno as follows:

{
  "mcpServers": {
    "runno": {
      "command": "npx",
      "args": ["@runno/mcp"]
    }
  }
}

There's an introduction article you can refer to for more information.

📚 Documentation

Development

Packages

This repository is divided into several packages using lerna:

• website - The Runno website containing instructions and examples.
• runtime - A library providing web components and helpers that can be bundled into your own project for using Runno without an iframe.
• wasi - A library for running WASI binaries in the browser.
• sandbox - A sandbox for running programming languages from any JavaScript runtime.
• mcp - An MCP Server implementation built on the sandbox.

Running locally

If you're lucky, everything should work after the following steps:

npm install
npm run bootstrap
npm run build  # make sure the dependent libraries are built
npm run dev

Testing

Runno has a small suite of tests, mainly focused on end-to-end integration. The wasi package has the most comprehensive test suite, thoroughly testing the WASI preview1 implementation. The other packages mostly have a few smoke tests to ensure they're working.

About Runno

Limitations

The available programming languages are limited by what has been compiled to Web Assembly using WASI. A great way to expand the available languages is to compile your favorite programming language tools to Web Assembly and upload them to WAPM.

WASI doesn't provide a full Linux environment, so most system-based interfaces won't work. Installing packages and modules inside the Runno environment is also difficult. If you want to import code, you need to provide it alongside your example.

Runno is best suited for small code examples that use STDIN and STDOUT, typically the kind taught in a CS1 course at university. However, this isn't an inherent limitation of the system. As more work is done on Runno and its dependent tools ecosystem, more functionality will become available.

Security

Runno is open-source software released under the MIT License, which states:

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

I stand by this lack of warranty. However, I believe the sandbox is quite good and I'm eager to make it even better. It's fun!

The main way the Runno sandbox isolates code is by running it as WebAssembly inside V8. WebAssembly has some useful properties:

1. Execution is virtualized, not running directly on your CPU and RAM.
2. Code and data are separate, preventing jumps into data.
3. The only interface with the outside world is through user-provided functions.

The last point (3) is the most important. If you run a WebAssembly binary without providing any functions, it literally can't do anything, like a box with no windows or doors.

However, we do want some data to flow in and out, which is where WASI comes in. WASI is a specification for an interface (the WebAssembly System Interface) that defines a standard set of functions that a WebAssembly binary can call as if they were system calls, mostly for reading and writing files.

Note: This is actually a definition of WASI preview1. Preview2 / 0.2 is different and very interesting but currently out of scope.

At its core, Runno is an implementation of WASI preview1, similar to a very lightweight operating system implemented in TypeScript. It has a virtual file system composed of virtual files (basically just byte arrays stored in memory), so it never accesses your real file system. It also has no network access or other similar capabilities.

So, 1) it's a virtual machine, 2) it has a virtual file system, and 3) it has no network access. That's quite secure.

There are many layers to this security mechanism, which I think is great. I've heard that layers are good for security. If you find any holes, please email security@taybenlor.com.

🤝 Big thanks to

A number of open-source projects and standards have made Runno possible:

• WASI and WebAssembly - Many people from various working groups, especially the Bytecode Alliance, have contributed to making WASM and WASI what they are today. Thanks a lot!
• XTerm.js - A fully featured terminal that can be run in the browser.
• CodeMirror - A great web-based code editor that's always a pleasure to integrate.
• Wasmer, WAPM, and WebAssembly.sh - The Wasmer team has built many great tools for running Web Assembly. WebAssembly.sh was a great inspiration and starting point.
• The extensive work by the web development community to make native code and APIs run successfully in the browser.

Thanks to everyone who has built compatibility layers for the web. The web becomes a better platform with every new piece of software we can run on it!

Also, big thanks to my friends who tolerate my constant talk about WASM. Special thanks to Katie, Jesse, Jim, Odin, Hailey, Sam, and other Sam.