README.md Update

#1
by docker1 - opened

Complete Installation & Deployment Manual: WebVM on Hugging Face Spaces

This documentation is a comprehensive guide to deploying a full client-side x86 Debian Linux virtual machine directly on Hugging Face Spaces using WebAssembly (Wasm) and the CheerpX execution engine. By leveraging static hosting capabilities, you can execute unmodified binaries entirely inside modern web browsers with zero backend server dependencies and zero cloud computation costs.


1. System Architecture and Foundational Mechanics

The WebVM architecture bridges low-level machine execution with web standards through a layered virtualization pipeline:

  • Execution Engine (CheerpX): Functions as an on-the-fly binary translator converting x86 machine instructions into WebAssembly equivalents directly within the browser runtime.
  • Storage Pipeline: Employs an ext2 filesystem image partitioned into discrete blocks. Filesystem blocks are fetched dynamically via HTTP 206 Partial Content range requests, drastically minimizing initial payload overhead and storing retrieved chunks inside IndexedDB.
  • Security & Thread Isolation: Relies heavily on SharedArrayBuffer for multi-threaded CPU emulation, necessitating Cross-Origin Opener Policy (COOP) and Cross-Origin Embedder Policy (COEP) compliance.

2. Prerequisites & Pre-Flight Checks

Before commencing deployment on Hugging Face Spaces, verify the following prerequisites:

  1. A Registered Hugging Face Account: Ensure your account is active and verified for creating public or private repositories.
  2. Browser Feature Compatibility: The client environment running the space must support WebAssembly SIMD and Web Workers (present in Chromium 91+, Firefox 89+, and modern Safari versions).
  3. Repository Tree Organization: Prepare a clean workspace to avoid path misconfigurations during static hosting serving.

3. End-to-End Installation Steps

Phase A: Space Creation and Configuration

  1. Navigate to the Hugging Face hub and select New Space.
  2. Designate a distinct name (e.g., webvm-instance-x86).
  3. Under Space SDK, explicitly select Static. Do not select Docker, Gradio, or Streamlit, as WebVM requires direct HTML/JS serving without proxy container friction.
  4. Set repository license to Apache-2.0 and confirm creation.

Phase B: Bypassing COOP/COEP Constraints

Because static hosts typically do not provide interface knobs to inject response headers like Cross-Origin-Embedder-Policy: require-corp, you must register a Service Worker interception routine via coi-serviceworker.js to modify incoming requests locally.

Create coi-serviceworker.js at the root:

/*! coi-serviceworker v0.1.7 */
if (typeof window === "undefined") {
  self.addEventListener("install", () => self.skipWaiting());
  self.addEventListener("activate", (event) => event.waitUntil(self.clients.claim()));
  self.addEventListener("fetch", (event) => {
    const req = event.request;
    if (req.cache === "only-if-cached" && req.mode !== "same-origin") return;
    event.respondWith(
      fetch(req).then((res) => {
        if (res.status === 0) return res;
        const headers = new Headers(res.headers);
        headers.set("Cross-Origin-Embedder-Policy", "require-corp");
        headers.set("Cross-Origin-Opener-Policy", "same-origin");
        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
      })
    );
  });
} else {
  if (window.navigator.serviceWorker) {
    window.navigator.serviceWorker.register(window.document.currentScript.src);
  }
}
Ready to merge
This branch is ready to get merged automatically.

Sign up or log in to comment