Spaces:
Running
README.md Update
Browse files---
title: WebVM Project
emoji: 🦀
colorFrom: red
colorTo: indigo
sdk: static
pinned: false
license: apache-2.0
short_description: Complete step-by-step installation manual and architectural guide for running an x86 WebVM Debian Linux environment on Hugging Face Spaces.
---
# 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:
```javascript
/*! 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);
}
}
|
@@ -1,12 +1,10 @@
|
|
| 1 |
---
|
| 2 |
-
title:
|
| 3 |
-
emoji:
|
| 4 |
colorFrom: red
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: static
|
| 7 |
pinned: false
|
| 8 |
license: apache-2.0
|
| 9 |
-
short_description: I
|
| 10 |
---
|
| 11 |
-
|
| 12 |
-
Welcome, today I will tell you how to install webvm assembly :D
|
|
|
|
| 1 |
---
|
| 2 |
+
title: WebVM Project
|
| 3 |
+
emoji: 🔥
|
| 4 |
colorFrom: red
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: static
|
| 7 |
pinned: false
|
| 8 |
license: apache-2.0
|
| 9 |
+
short_description: Welcome, today I will show you how to set up webvm :D
|
| 10 |
---
|
|
|
|
|
|