{
"markdown": "šØāš» **Use Runno** š [Runno.dev](https://runno.dev/)\n\nš **Documentation** š [Runno.dev](https://runno.dev/docs/)\n\n# Runno\n\nRunno is a collection of JavaScript Packages for running code in various languages\ninside a sandbox. It's made of the following packages:\n\n- [`@runno/runtime`](https://github.com/taybenlor/runno/tree/main/packages/runtime) - web components and headless tools for running code examples in the browser.\n- [`@runno/sandbox`](https://github.com/taybenlor/runno/tree/main/packages/sandbox) - a secure sandbox for running code examples in Node and other JS Runtimes.\n- [`@runno/wasi`](https://github.com/taybenlor/runno/tree/main/packages/wasi) - an isomorphic package for running WebAssembly WASI binaries inside a sandbox.\n- [`@runno/mcp`](https://github.com/taybenlor/runno/tree/main/packages/mcp) - an MCP Server for running code using the `@runno/sandbox` package.\n\nThere's also a deprecated Python package called [`runno`](https://github.com/taybenlor/runno/tree/main/sandbox)\nthat works like the sandbox package.\n\nThis project is powered by [WASI](https://wasi.dev) the Web Assembly System\nInterface. It provides a standard way for programs to interact with an\noperating system. By emulating this interface, we can provide a fake file system\nand operating system, all running within JavaScript.\n\n# Using `@runno/runtime`\n\nThe `@runno/runtime` package provides Web Components for running code in the browser.\n\nThis is very handy for programming education it means:\n\n- No need for newbies to install complex programming tools to run code\n- Programming examples can be made runnable in the browser with no server\n- Simple programs can be tested for correctness inside a sandbox on the user's machine\n\n## Quickstart\n\nStart by adding `@runno/runtime` to your package:\n\n```sh\nnpm install @runno/runtime\n```\n\nImport `@runno/runtime` in whatever place you'll be using the runno elements.\nThe simplest is in your entrypoint file (e.g. `main.ts` or `index.ts`).\n\n```js\nimport \"@runno/runtime\";\n```\n\nOnce you've imported them you can use runno elements on the page.\n\n```html\n print('Hello, World!') \n```\n\nFor the code to run though, you'll need to set some HTTP headers:\n\n```\nCross-Origin-Opener-Policy: same-origin\nCross-Origin-Embedder-Policy: require-corp\n```\n\nThese create a [cross-origin isolated context](https://web.dev/cross-origin-isolation-guide/) which allows the use of `SharedArrayBuffer` used to implement STDIN.\n\n## Supported Runtimes\n\nThe system supports a number of runtimes based on existing packages published to WAPM. These runtimes are tied to Runno and will be supported by Runno going forward.\n\n- `python` - Runs python3 code, not pinned to a particular version but is at least `3.6`\n- `ruby` - Runs standard Ruby, not pinned but is at least `3.2.0`\n- `quickjs` - Runs JavaScript code using the [QuickJS](https://bellard.org/quickjs/) engine\n- `sqlite` - Runs SQLite commands\n- `clang` - Compiles and runs C code\n- `clangpp` - Compiles and runs C++ code\n- `php-cgi` - Runs PHP CGI compiled by VMWare\n\n## Running WASI binaries\n\nThe runtime also provides a component for running WASI binaries directly.\n\n```html\n\n```\n\n## Examples\n\nThere are more examples for how to use Runno in the `examples` directory in this\nrepo. It includes practical ways you can use Runno, and how to configure it to\nrun.\n\n## Full documentation\n\nVisit [`@runno/runtime`](https://github.com/taybenlor/runno/tree/main/packages/runtime) to read the full documentation.\n\n## How does it work?\n\nRunno uses Web Assembly to run code from JavaScript. Code runs in a unix-like sandbox that connects to a web-based terminal emulator. This means it behaves a lot like running code natively on a linux terminal. It's not perfect, but it's handy for making code examples run.\n\nPlus it's pretty cool that you can just run code in your browser!\n\n# Using `@runno/sandbox`\n\n## Quickstart\n\nInstall the sandbox with `npm install @runno/sandbox`. Then use it to run code\nlike:\n\n```ts\nimport { runCode } from \"@runno/sandbox\";\n\nconst result = await runCode(\"ruby\", \"puts 'Hello, world!'\");\n\nif (result.resultType === \"complete\") {\n console.log(result.stdout);\n} else {\n console.log(\"Oh no!\");\n}\n```\n\nYou can also do more complicated things, like run against a virtual file system\nwith `runFS`:\n\n```ts\nfunction runFS(\n runtime: Runtime,\n entryPath: string,\n fs: WASIFS,\n options?: {\n stdin?: string;\n timeout?: number;\n },\n): Promise;\n```\n\n# Using `@runno/wasi`\n\n## Quickstart\n\nThe quickest way to get started with Runno is by using the `WASI.start` class\nmethod. It will set up everything you need and run the Wasm binary directly.\n\nBe aware that this will run on the main thread, not inside a worker. So you will\ninterrupt any interactive use of the browser until it completes.\n\n```js\nimport { WASI } from \"@runno/wasi\";\n\n//...\n\nconst result = WASI.start(fetch(\"/binary.wasm\"), {\n args: [\"binary-name\", \"--do-something\", \"some-file.txt\"],\n env: { SOME_KEY: \"some value\" },\n stdout: (out) => console.log(\"stdout\", out),\n stderr: (err) => console.error(\"stderr\", err),\n stdin: () => prompt(\"stdin:\"),\n fs: {\n \"/some-file.txt\": {\n path: \"/some-file.txt\",\n timestamps: {\n access: new Date(),\n change: new Date(),\n modification: new Date(),\n },\n mode: \"string\",\n content: \"Some content for the file.\",\n },\n },\n});\n```\n\nYou can see a more complete example in `src/main.ts`.\n\n_Note: The `args` should start with the name of the binary. Like when you run\na terminal command, you write `cat somefile` the name of the binary is `cat`._\n\n# Full documentation\n\nVisit [`@runno/wasi`](https://github.com/taybenlor/runno/tree/main/packages/wasi) to read the full documentation including instructions for running inside a worker, and how the\nvirtual file-system works.\n\n# Using `@runno/sandbox`\n\n## Quickstart\n\nThe sandbox exports a `runCode` function you can use to run code. First install it with `npm install @runno/sandbox` or however you are installing packages. Then do something like:\n\n```ts\nimport { runCode } from \"@runno/sandbox\";\n\nconst result = await runCode(\"ruby\", \"puts 'Hello JavaScript!'\");\n\nconsole.log(\"Ruby says:\", result.stdout);\n```\n\nThere's an [introduction article](https://runno.dev/articles/sandbox/) you can use to learn more.\n\n# Using `@runno/mcp`\n\n## Quickstart\n\nDepending on how your MCP server is configured, you can add Runno with:\n\n```json\n{\n \"mcpServers\": {\n \"runno\": {\n \"command\": \"npx\",\n \"args\": [\"@runno/mcp\"]\n }\n }\n}\n```\n\nThere's an [introduction article](https://runno.dev/articles/mcp/) you can use to learn more.\n\n# Development\n\n## Packages\n\nThis repo is broken down into a few packages using [lerna](https://lerna.js.org/):\n\n- `website` - the runno website that includes instructions and examples\n- `runtime` - a library that provides web components and helpers that can be bundled into your own project for using runno without an iframe\n- `wasi` - a library for running WASI binaries in the browser\n- `sandbox` - a sandbox for running programming languages from any JavaScript runtime\n- `mcp` - an MCP Server implementation built on the `sandbox`\n\n## Running locally\n\nIf you're lucky everything should work after doing:\n\n```sh\nnpm install\nnpm run bootstrap\nnpm run build # make sure the dependent libraries are built\nnpm run dev\n```\n\n## Testing\n\nRunno has a small suite of tests, mostly focused on end-to-end integration. The `wasi` package has the most extensive suite of tests, comprehensively testing the WASI preview1 implementation. The other packages mostly have a few smoke tests to make sure they're working.\n\n# About Runno\n\n## Limitations\n\nThe programming languages available are limited by what has already been compiled to Web Assembly using WASI. A great way to help more languages become available would be to compile your favourite programming language tools to Web Assembly and upload them to WAPM.\n\nWASI doesn't provide a full linux environment, so most system based interfaces won't work. Packages and modules are also difficult to install inside the Runno environment. If you want to import code, you'll need to provide that code alongside your example.\n\nRunno is best for small code examples that use STDIN and STDOUT. That is typically the sort of thing that is taught in a CS1 course at university. This isn't an inherent limitation of the system though! As more work is put into Runno and the ecosystem of tools it depends on, more will become available.\n\n## Security\n\nI do want to say up front that Runno is Open Source software with an MIT\nLicense, which specifically states:\n\n```\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND\n```\n\nI stand by that lack of a warranty. But I also think the sandbox is pretty good\nand I'd love to make it really good. It's fun.\n\nThe main way that the Runno sandbox isolates code is by running it as\nWebAssembly inside V8. WebAssembly has some neat properties:\n\n1. Execution is all virtualised, it's not running directly on your CPU and RAM\n2. Code and Data are seperate, you can't jump into data\n3. The only interface with the outside world is via user-provided functions\n\nThat last point (3) is the most important one. If you run a WebAssembly binary\nand don't provide it with any functions it literally cannot do anything. It's\nlike a box with no windows or doors, nothing can get in or out.\n\nBut we do want some things to get in and out. That's what WASI is for. WASI is a\nspecification for an interface (the WebAssembly System Interface) that defines\na standard set of functions that a WebAssembly binary can call like they are\nsystem calls. Mostly they do things like read and write files.\n\n_Note: this is actually a definition of WASI preview1, preview2 / 0.2 is a\ndifferent beast and is very cool but currently out of scope._\n\nRunno at it's core is an implementation of WASI preview1. It's kind of like a\nvery lightweight Operating System implemented in TypeScript. It has a virtual\nfile system which is made up of virtual files (basically just byte arrays stored\nin memory). So it never accesses your real file system either. It also has no\nnetwork access or anything else like that.\n\nSo 1) it's a virtual machine, 2) it's a virtual file system, and 3) it has no\nnetwork access. That's pretty good.\n\nThere's a lot of layers to this onion which I think is pretty good. I've heard\nonions are good for security. Tell me if you find some holes in my onion though,\nI'm interested! Email [security@taybenlor.com](mailto:security@taybenlor.com).\n\n# Big thanks to\n\nA number of open-source projects and standards have been used to make Runno possible. These include:\n\n- WASI and WebAssembly - a bunch of people from various working groups and especially the Bytecode Alliance have been involved in making WASM and WASI what it is today. Thanks heaps!\n\n- [XTerm.js](https://xtermjs.org/) - a fully featured terminal that can be run in the browser\n\n- [CodeMirror](https://codemirror.net) - a great web-based code editor that's always a delight to integrate\n\n- [Wasmer](https://wasmer.io/), [WAPM](https://wapm.io/), and [WebAssembly.sh](https://webassembly.sh) - the Wasmer team have built a lot of great tools for running Web Assembly. WebAssembly.sh was a great inspiration and starting point.\n\n- The extensive work by many in the web development community on making native code and APIs run successfully inside the browser.\n\nThanks 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!\n\nAlso big thanks to my friends who tolerate me constantly talking about WASM. Thanks especially to Katie, Jesse, Jim, Odin, Hailey, Sam and other Sam.\n",
"bytes": 11828,
"sha": "6f33e1329887e856ccb9c1608596d191bc4e24d86702e6e125ba7529b3fd1b4f",
"repo_slug": "taybenlor/runno",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_taybenlor_runno_70ebe1e3/readme"
}