Runno

🚀 Runno

Runno 是一組 JavaScript 包，用於在沙箱環境中運行多種語言的代碼。它能為用戶提供一個安全且便捷的代碼運行環境，無需複雜的本地配置，即可在瀏覽器或其他 JavaScript 運行時中運行代碼示例。

👨‍💻 使用 Runno 👉 Runno.dev

📖 文檔 👉 Runno.dev

🚀 快速開始

使用 @runno/runtime

首先，將 @runno/runtime 添加到你的項目中：

npm install @runno/runtime

在你要使用 Runno 元素的地方導入 @runno/runtime，最簡單的做法是在入口文件（如 main.ts 或 index.ts）中導入：

import "@runno/runtime";

導入後，你就可以在頁面上使用 Runno 元素了：

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

不過，要使代碼能夠運行，你需要設置一些 HTTP 頭：

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

這些頭信息會創建一個 跨源隔離上下文，允許使用 SharedArrayBuffer 來實現標準輸入（STDIN）。

使用 @runno/sandbox

使用 npm install @runno/sandbox 安裝沙箱，然後使用它來運行代碼，示例如下：

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!");
}

你還可以做更復雜的事情，比如使用 runFS 針對虛擬文件系統運行代碼：

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

使用 @runno/wasi

使用 WASI.start 類方法是快速開始使用 Runno 的方法。它將為你設置好所需的一切並直接運行 WebAssembly 二進制文件。 請注意，這將在主線程上運行，而不是在工作線程中。因此，在運行完成之前，它會中斷瀏覽器的任何交互操作。

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.",
    },
  },
});

你可以在 src/main.ts 中查看更完整的示例。

使用 @runno/mcp

根據你的 MCP 服務器配置，你可以通過以下方式添加 Runno：

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

✨ 主要特性

Runno 由以下幾個包組成：

• @runno/runtime - 用於在瀏覽器中運行代碼示例的 Web 組件和無頭工具。
• @runno/sandbox - 用於在 Node 和其他 JavaScript 運行時中運行代碼示例的安全沙箱。
• @runno/wasi - 用於在沙箱中運行 WebAssembly WASI 二進制文件的同構包。
• @runno/mcp - 一個使用 @runno/sandbox 包運行代碼的 MCP 服務器。

此外，還有一個已棄用的 Python 包 runno，其功能類似於沙箱包。

📦 安裝指南

本地運行

如果你運氣好，執行以下操作後一切應該都能正常工作：

npm install
npm run bootstrap
npm run build  # 確保依賴庫已構建
npm run dev

💻 使用示例

運行 WASI 二進制文件

運行時還提供了一個直接運行 WASI 二進制文件的組件：

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

更多示例

在本倉庫的 examples 目錄中有更多關於如何使用 Runno 的示例，其中包含了一些實際使用 Runno 的方法以及如何配置它來運行代碼。

📚 詳細文檔

@runno/runtime

訪問 @runno/runtime 閱讀完整文檔。

@runno/wasi

訪問 @runno/wasi 閱讀完整文檔，其中包括在工作線程中運行的說明以及虛擬文件系統的工作原理。

學習更多

你可以閱讀以下介紹文章來了解更多信息：

• Sandbox 介紹文章
• MCP 介紹文章

🔧 技術細節

工作原理

Runno 使用 Web Assembly 從 JavaScript 中運行代碼。代碼在一個類似 Unix 的沙箱中運行，該沙箱連接到一個基於 Web 的終端模擬器。這意味著它的行為很像在 Linux 終端上本地運行代碼。雖然它並不完美，但對於運行代碼示例來說非常方便。

支持的運行時

該系統支持基於已發佈到 WAPM 的現有包的多種運行時。這些運行時與 Runno 相關聯，並且 Runno 將持續支持它們：

開發相關

本倉庫使用 lerna 拆分為幾個包：

• website - Runno 網站，包含使用說明和示例
• runtime - 一個庫，提供 Web 組件和助手，可打包到你自己的項目中，無需使用 iframe 即可使用 Runno
• wasi - 一個用於在瀏覽器中運行 WASI 二進制文件的庫
• sandbox - 一個用於在任何 JavaScript 運行時中運行編程語言的沙箱
• mcp - 一個基於 sandbox 構建的 MCP 服務器實現

測試

Runno 有一套小型測試，主要側重於端到端集成測試。wasi 包擁有最廣泛的測試套件，全面測試了 WASI preview1 實現。其他包主要有一些冒煙測試，以確保它們能夠正常工作。

📄 許可證

Runno 是開源軟件，採用 MIT 許可證，具體聲明如下：

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

關於 Runno

侷限性

可用的編程語言受到已使用 WASI 編譯為 Web Assembly 的工具的限制。要讓更多語言可用，一個好方法是將你喜歡的編程語言工具編譯為 Web Assembly 並上傳到 WAPM。

WASI 不提供完整的 Linux 環境，因此大多數基於系統的接口將無法工作。在 Runno 環境中安裝包和模塊也很困難。如果你想導入代碼，則需要在示例中提供該代碼。

Runno 最適合使用標準輸入（STDIN）和標準輸出（STDOUT）的小代碼示例，這通常是大學 CS1 課程中所教授的內容。但這並不是該系統的固有侷限性！隨著對 Runno 及其依賴的工具生態系統投入更多的工作，將會有更多功能可用。

安全性

Runno 的沙箱主要通過在 V8 中以 WebAssembly 形式運行代碼來隔離代碼。WebAssembly 具有以下一些特性：

1. 執行是完全虛擬化的，它不會直接在你的 CPU 和內存上運行。
2. 代碼和數據是分離的，你無法跳轉到數據中。
3. 與外部世界的唯一接口是通過用戶提供的函數。

最後一點是最重要的。如果你運行一個 WebAssembly 二進制文件而不提供任何函數，它實際上什麼也做不了，就像一個沒有窗戶或門的盒子，什麼也進不去也出不來。

Runno 的核心是 WASI preview1 的實現，它有點像一個用 TypeScript 實現的非常輕量級的操作系統。它有一個虛擬文件系統，由虛擬文件（基本上只是存儲在內存中的字節數組）組成，因此它也不會訪問你的真實文件系統，並且沒有網絡訪問或其他類似功能。

如果你發現了 Runno 安全方面的漏洞，請發送郵件至 security@taybenlor.com。

特別感謝

許多開源項目和標準使得 Runno 成為可能，其中包括：

• WASI 和 WebAssembly - 來自各個工作組的許多人，特別是 Bytecode Alliance 的成員，為 WASM 和 WASI 的發展做出了貢獻。非常感謝！
• XTerm.js - 一個可以在瀏覽器中運行的功能齊全的終端。
• CodeMirror - 一個優秀的基於 Web 的代碼編輯器，集成起來總是很愉快。
• Wasmer、WAPM 和 WebAssembly.sh - Wasmer 團隊為運行 Web Assembly 構建了許多優秀的工具。WebAssembly.sh 是一個很好的靈感來源和起點。
• 網絡開發社區中許多人為使原生代碼和 API 能夠在瀏覽器中成功運行所做的大量工作。

感謝每一位為網絡構建兼容性層的人。隨著我們能夠在網絡上運行的新軟件越來越多，網絡將成為一個更好的平臺！

同時，也非常感謝我的朋友們，他們忍受我不斷談論 WASM。特別感謝 Katie、Jesse、Jim、Odin、Hailey、Sam 和另一個 Sam。