From 0d81cca20e8705a8f4d2e0280a94bff8ed962a8e Mon Sep 17 00:00:00 2001 From: codingfrog27 Date: Mon, 30 Mar 2026 18:30:32 +0200 Subject: [PATCH 01/16] first pass --- README.md | 314 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 189 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index e73e58223..353c5b026 100644 --- a/README.md +++ b/README.md @@ -9,32 +9,64 @@ Try out the new Alpine / Xorg / i3 graphical environment: [https://webvm.io/alpi -WebVM is a server-less virtual environment running fully client-side in HTML5/WebAssembly. It's designed to be Linux ABI-compatible. It runs an unmodified Debian distribution including many native development toolchains. +## What is WebVM? -WebVM is powered by the CheerpX virtualization engine, and enables safe, sandboxed client-side execution of x86 binaries on any browser. CheerpX includes an x86-to-WebAssembly JIT compiler, a virtual block-based file system, and a Linux syscall emulator. +WebVM is a server-less virtual environment running fully client-side in HTML5/WebAssembly. It's designed to be Linux ABI-compatible and runs an unmodified Debian distribution including many native development toolchains. + +WebVM is powered by the **CheerpX** virtualization engine, which provides: +- x86-to-WebAssembly JIT compiler +- Virtual block-based file system +- Linux syscall emulator +- Safe, sandboxed client-side execution ## Table of Contents -- [Fork, deploy, customize](#fork-deploy-customize) -- [Running WebVM locally with a custom Debian mini disk image](#run-webvm-locally-with-a-custom-debian-mini-disk-image) -- [Example customization: Python3 REPL](#example-customization-python3-repl) -- [How to use Claude AI](#how-to-use-claude-ai) -- [Bugs and Issues](#bugs-and-issues) -- [More links](#more-links) -- [Thanks to...](#thanks-to) -- [Versioning](#versioning) +- [Quick Start](#quick-start) +- [Networking](#networking) +- [Development & Customization](#development--customization) + - [Deploy to GitHub Pages](#deploy-to-github-pages) + - [Build Custom Disk Images](#building-custom-disk-images) + - [Run Locally](#run-webvm-locally) + - [Example: Python3 REPL](#example-python3-repl) +- [Features](#features) + - [Claude AI Integration](#claude-ai-integration) +- [Community & Support](#community--support) +- [Learn More](#learn-more) - [License](#license) -# Enable networking +## Quick Start + +### Online (No Installation) + +Visit [https://webvm.io](https://webvm.io) to get started immediately in your browser. No setup required. + +### Local Development + +If you'd like to run WebVM locally: + +```sh +git clone https://github.com/leaningtech/webvm.git +cd webvm +npm install && npm run build +nginx -p . -c nginx.conf +``` + +Then open `http://127.0.0.1:8081` in your browser. -Modern browsers do not provide APIs to directly use TCP or UDP. WebVM provides networking support by integrating with Tailscale, a VPN network that supports WebSockets as a transport layer. +For detailed local setup with custom images, see [Run Locally](#run-webvm-locally-with-a-custom-debian-mini-disk-image). -1. Open the "Networking" panel from the side-bar -2. Click "Connect to Tailscale" from the panel -3. Log in to Tailscale (create an account if you don't have one) -4. Click "Connect" when prompted by Tailscale +## Networking -WebVM now has access to machines in your own local Tailscale Network! +Modern browsers don't provide TCP/UDP sockets directly. WebVM supports networking via **Tailscale**, a WireGuard-based VPN with WebSocket support. + +### Quick Setup + +1. Open the "Networking" panel from the sidebar +2. Click "Connect to Tailscale" +3. Log in (create a free account at [tailscale.com](https://tailscale.com) if needed) +4. Click "Connect" when prompted + +WebVM now has access to all machines in your Tailscale network! ## The world wide web @@ -42,144 +74,167 @@ If you would like to access the public internet, you will need to set up an Exit See the _"Advertise a device as an exit node"_ section of the [Tailscale Exit Node quickstart guide](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux) for instructions. (The _“Use an exit node”_ section can be skipped, as WebVM automatically uses an available exit node once one is advertised). > [!NOTE] -> While we support most network commands there are a few that rely on kernel-level features not available in modern browsers and are therefore not supported, most notably `ping`.You could use `curl` or `wget` for testing instead. - -(Depending on your network speed, you may need to wait a few moments for the Tailscale Wasm module to be downloaded.) -Once that is set up: -1. Log in with your Tailscale credentials. -2. Go back to the WebVM tab. -3. The `Connect to Tailscale` button in the Networking side-panel should be replaced by your IP address. +> Some commands like `ping` require kernel features unavailable in browsers. Use `curl` or `wget` instead. > [!TIP] -> You can also check your connection status by checking the dot colour on the "connect to tailscale" button (which should now show your tailscale IP). On local network connectivity it will be orange, global will be green. - -## Using an authkey +> Connection status is shown as a colored dot on the button: orange = local network, green = global/internet. The button text shows your Tailscale IP address once connected. -As an alternative to manually logging in, you can add your tailscale auth Key at the end of the webvm URL. +### Internet Access (Exit Node) -`https://webvm.io/#authKey=` +To access the public internet from WebVM, set up an **Exit Node** on another device in your Tailscale network: -It is recommended to use an ephemeral key. +1. Follow the [Tailscale Exit Node quickstart](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux) (sections: "Advertise a device as an exit node") +2. WebVM automatically uses the exit node once advertised -## Selfhosting your tailscale network +### Authentication Options -We also support [headscale](https://headscale.net/stable/), a selfhosted open source implementation of the Tailscale control server. +**Via API key (for automation):** +``` +https://webvm.io/#authKey= +``` -Though as headscale unfortunately doesn't support adding CORS headers. You will have to set up a proxy server to add them. Headscales instructions on doing so can be found [here](https://headscale.net/stable/ref/integration/reverse-proxy/#nginx). +**Via Headscale (self-hosted Tailscale):** -Once ready, add the following line to your `location /` block in your nginx config file. +Headscale doesn't support CORS by default. Set up an Nginx proxy with CORS headers: -``` Nginx - if ($http_origin = "https://webvm.io") { - add_header 'Access-Control-Allow-Origin' "$http_origin"; - add_header 'Access-Control-Allow-Credentials' 'true' always; - } +```nginx +if ($http_origin = "https://yourdomain.com") { + add_header 'Access-Control-Allow-Origin' "$http_origin"; + add_header 'Access-Control-Allow-Credentials' 'true' always; +} ``` +Then access WebVM with: +``` +https://yourdomain.com/#controlUrl= +``` -To log in to your headscale network add `#controlUrl=` to the webVM url. +See [Headscale Nginx integration docs](https://headscale.net/stable/ref/integration/reverse-proxy/#nginx) for more details. **Notes:** +- If self-hosting, replace URLs with your own domain +- This is equivalent to the Tailscale `--login-server` option +- When using both `authKey` and `controlUrl`, separate them with `&`: `#authKey=...&controlUrl=...` + -- If self hosting, replace "https://webvm.io" with your own url. -- This is equivelant to the tailscale `--login-server` command line option. -- If used with authkey, don't forget to seperate the URL fragments with a `&` inbetween. +## Development & Customization +### Deploy to GitHub Pages -# Fork, deploy, customize +Fork the WebVM repository to deploy your own version to GitHub Pages: deploy_instructions_gif -- Fork the repository. -- Enable Github pages in settings. - - Click on `Settings`. - - Go to the `Pages` section. - - Select `Github Actions` as the source. - - If you are using a custom domain, ensure `Enforce HTTPS` is enabled. -- Run the workflow. - - Click on `Actions`. - - Accept the prompt. This is required only once to enable Actions for your fork. - - Click on the workflow named `Deploy`. - - Click `Run workflow` and then once more `Run workflow` in the menu. -- After a few seconds a new `Deploy` workflow will start, click on it to see details. -- After the workflow completes, which takes a few minutes, it will show the URL below the `deploy_to_github_pages` job. +1. **Fork the repository** (click the Fork button on GitHub) +2. **Enable GitHub Pages:** + - Go to Settings → Pages + - Select "GitHub Actions" as the source + - Enable "Enforce HTTPS" if using a custom domain +3. **Run the Deploy workflow:** + - Go to Actions → Click "Deploy" workflow + - Click "Run workflow" twice (once in the dropdown menu) +4. After a few minutes, the workflow will show your deployed URL below the `deploy_to_github_pages` job - + -You can now customize `dockerfiles/debian_mini` to suit your needs, or make a new Dockerfile from scratch. Use the `Path to Dockerfile` workflow parameter to select it. +### Building Custom Disk Images -- If you would like to use our full desktop Alpine image, you can find it's dockerfile [**here**](https://github.com/leaningtech/alpine-image). +You can customize the Debian mini image or create entirely new disk images using the **Deploy workflow**. -- For more information on creating custom images, see our [Custom disk Image documentation](https://cheerpx.io/docs/guides/custom-images). +The workflow builds a custom Dockerfile into a bootable `.ext2` disk image and can either: +- **Upload to GitHub Release** — Download and use locally +- **Deploy to GitHub Pages** — Use remotely from your fork +**To build a custom image:** -# Run WebVM locally with a custom Debian mini disk image +1. Modify `dockerfiles/debian_mini` or create a new Dockerfile +2. Go to Actions → "Deploy" workflow → "Run workflow" +3. Set the "Path to Dockerfile" parameter to your Dockerfile +4. Choose deployment: "Upload as release" or "Deploy to pages" +5. After the workflow completes, download the `.ext2` file (from Releases tab if you chose "Upload as release") -### 1. Clone the WebVM Repository +**To use a custom image locally:** + +1. Save the `.ext2` file to `custom-disk-images/` +2. In `config_public_terminal.js`, set: + ```js + diskImageUrl = "/custom-disk-images/your-image.ext2" + diskImageType = "bytes" + ``` +3. Rebuild: `npm install && npm run build` + +**For the full Alpine desktop environment:** + +Our Alpine/Xorg/i3 environment Dockerfile is available [here](https://github.com/leaningtech/alpine-image). + +**For more details:** + +See the [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). + +### Run WebVM Locally + +#### 1. Clone the WebVM Repository ```sh git clone https://github.com/leaningtech/webvm.git cd webvm ``` -### 2. Download the Debian mini Ext2 image +#### 2. Put your local image in `custom-disk-images/` + +This repository includes a persistent `custom-disk-images/` directory for local `.ext2` files. -Run the following command to download the Debian mini Ext2 image: +Download the Debian mini image into that directory: ```sh -wget "https://github.com/leaningtech/webvm/releases/download/ext2_image/debian_mini_20230519_5022088024.ext2" +wget -O custom-disk-images/debian_mini_20230519_5022088024.ext2 \ + "https://github.com/leaningtech/webvm/releases/download/ext2_image/debian_mini_20230519_5022088024.ext2" ``` -(*You can also build your own disk image by selecting the **"Upload GitHub release"** workflow option*) +(*You can also build your own image and copy it into `custom-disk-images/`.*) -### 3. Update the configuration file +#### 3. Configure WebVM to use the local image - Edit `config_public_terminal.js` to reference your local disk image: +Edit `config_public_terminal.js`: -- Replace: - - `"wss://disks.webvm.io/debian_large_20230522_5044875331.ext2"` - - With: - - `"/disk-images/debian_mini_20230519_5022088024.ext2"` +- Set `diskImageUrl` to your local file URL, for example: - (*Use an absolute or relative URL pointing to the disk image location.*) + `"/custom-disk-images/debian_mini_20230519_5022088024.ext2"` +- Set `diskImageType` to: -- Replace `"cloud"` with the correct disk image type: `"bytes"` + `"bytes"` - -### 4. Build WebVM +#### 4. Build WebVM -Run the following commands to install dependencies and build WebVM: +Install dependencies and build: ```sh npm install npm run build ``` -The output will be placed in the `build` directory. - -### 5. Configure Nginx +The web assets are generated into `build/`. -- Create a directory for the disk image: - -```sh -mkdir disk-images -mv debian_mini_20230519_5022088024.ext2 disk-images/ -``` +#### 5. Configure Nginx -- Modify your `nginx.conf` file to serve the disk image. Add the following location block: +Keep your existing `location /` that serves `build/`, and add a separate location for custom images: ```nginx -location /disk-images/ { - root .; - autoindex on; +location /custom-disk-images/ { + alias ./custom-disk-images/; } ``` -### 6, Start Nginx +Why this separate location is needed: + +- `location /` points to `build/`, but the image file lives outside `build/`. +- If you try to serve images only through `location /`, Nginx will look under `build/custom-disk-images/...`. +- Keeping images outside `build/` avoids losing them on future `npm run build` runs. + +`autoindex` is optional and not required for WebVM disk loading. It can stay off. + +#### 6. Start Nginx Run the following command to start Nginx: @@ -187,19 +242,23 @@ Run the following command to start Nginx: nginx -p . -c nginx.conf ``` -*Nginx will automatically serve the build directory.* +#### 7. Verify that the local image is actually being used -### 7. Access WebVM +In another shell, inspect access logs while loading WebVM: -Open a browser and visit: `http://127.0.0.1:8081`. +```sh +tail -f nginx_access.log | grep --line-buffered custom-disk-images +``` -Enjoy your local WebVM! +You should see repeated `206` responses for `/custom-disk-images/...ext2`. ---- +#### 8. Access WebVM +Open a browser and visit: `http://127.0.0.1:8081`. +Enjoy your local WebVM! -# Example customization: Python3 REPL +### Example: Python3 REPL The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy. @@ -216,66 +275,71 @@ index 2878332..1f3103a 100644 +CMD [ "/usr/bin/python3" ] ``` -# How to use Claude AI +## Features + +### Claude AI Integration To access Claude AI, you need an API key. Follow these steps to get started: -### 1. Create an account +#### 1. Create an account - Visit [Anthropic Console](https://console.anthropic.com/login) and sign up with your e-mail. You'll receive a sign in link to the Anthropic Console. -### 2. Get your API key +#### 2. Get your API key - Once logged in, navigate to **Get API keys**. - Purchase the amount of credits you need. After completing the purchase, you'll be able to generate the key through the API console. -### 3. Log in with your API key +#### 3. Log in with your API key - Navigate to your WebVM and hover over the robot icon. This will show the Claude AI Integration tab. For added convenience, you can click the pin button in the top right corner to keep the tab in place. - You'll see a prompt where you can insert your Claude API key. - Insert your key and press enter. -### 4. Start using Claude AI +#### 4. Start using Claude AI - Once your API key is entered, you can begin interacting with Claude AI by asking questions such as: __"Solve the CTF challenge at `/home/user/chall1.bin.` Note that the binary reads from stdin."__ deploy_instructions_gif -**Important:** Your API key is private and should never be shared. We do not have access to your key, which is not only stored locally in your browser. +**Important:** Your API key is private and should never be shared. We do not have access to your key, it is only stored locally in your browser. + +## Community & Support -# Bugs and Issues +**Report issues:** Use [GitHub Issues](https://github.com/leaningtech/webvm/issues) to report bugs or request features. -Please use [Issues](https://github.com/leaningtech/webvm/issues) to report any bug. -Or come to say hello / share your feedback on [Discord](https://discord.gg/yTNZgySKGa). +**Chat with us:** Join our [Discord community](https://discord.gg/yTNZgySKGa) to discuss WebVM, share ideas, and get help. -# More links +## Learn More -- [WebVM: server-less x86 virtual machines in the browser](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) +**Articles & Resources:** +- [WebVM: Server-less x86 virtual machines in the browser](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) - [WebVM: Linux Virtualization in WebAssembly with Full Networking via Tailscale](https://leaningtech.com/webvm-virtual-machine-with-networking-via-tailscale/) - [Mini.WebVM: Your own Linux box from Dockerfile, virtualized in the browser via WebAssembly](https://leaningtech.com/mini-webvm-your-linux-box-from-dockerfile-via-wasm/) -- Reference GitHub Pages deployment: [Mini.WebVM](https://mini.webvm.io) -- [Crafting the Impossible: X86 Virtualization in the Browser with WebAssembly](https://www.youtube.com/watch?v=VqrbVycTXmw) Talk at JsNation 2022 +- [Crafting the Impossible: X86 Virtualization in the Browser with WebAssembly](https://www.youtube.com/watch?v=VqrbVycTXmw) — Talk at JsNation 2022 + +**Example Deployment:** +- [Mini.WebVM Reference](https://mini.webvm.io) — A running example deployed to GitHub Pages -# Thanks to... -This project depends on: -- [CheerpX](https://cheerpx.io/), made by [Leaning Technologies](https://leaningtech.com/) for x86 virtualization and Linux emulation -- xterm.js, [https://xtermjs.org/](https://xtermjs.org/), for providing the Web-based terminal emulator -- [Tailscale](https://tailscale.com/), for the networking component -- [lwIP](https://savannah.nongnu.org/projects/lwip/), for the TCP/IP stack, compiled for the Web via [Cheerp](https://github.com/leaningtech/cheerp-meta/) +**Technology Behind WebVM:** -# Versioning +This project is powered by: +- **[CheerpX](https://cheerpx.io/)** — x86-to-WebAssembly JIT compiler | by [Leaning Technologies](https://leaningtech.com/) +- **[xterm.js](https://xtermjs.org/)** — Web-based terminal emulator +- **[Tailscale](https://tailscale.com/)** — VPN networking layer +- **[lwIP](https://savannah.nongnu.org/projects/lwip/)** — TCP/IP stack, compiled for the Web via [Cheerp](https://github.com/leaningtech/cheerp-meta/) -WebVM depends on the CheerpX x86-to-WebAssembly virtualization technology, which is included in the project via [NPM](https://www.npmjs.com/package/@leaningtech/cheerpx). +**Versioning:** -The NPM package is updated on every release. +WebVM uses the [CheerpX](https://www.npmjs.com/package/@leaningtech/cheerpx) NPM package, which is updated on every release. -Every build is immutable, if a specific version works well for you today, it will keep working forever. +Every build is immutable. If a specific version works well for you today, it will keep working forever. -# License +## License WebVM is released under the Apache License, Version 2.0. From d22aceaf67226148045dc74aacdceba6f861150f Mon Sep 17 00:00:00 2001 From: codingfrog27 Date: Mon, 20 Apr 2026 14:53:23 +0200 Subject: [PATCH 02/16] second pass --- .gitignore | 4 +- README.md | 191 ++++++++++---------------------------- config_public_terminal.js | 4 +- nginx.conf | 6 +- 4 files changed, 58 insertions(+), 147 deletions(-) diff --git a/.gitignore b/.gitignore index 1807dedf9..aeab15586 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ /node_modules /.svelte-kit pnpm-lock.yaml -build/ \ No newline at end of file +build/ +custom-disk-images/* +!custom-disk-images/.gitkeep \ No newline at end of file diff --git a/README.md b/README.md index 353c5b026..387f1fc2b 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,8 @@ WebVM is powered by the **CheerpX** virtualization engine, which provides: - [Quick Start](#quick-start) - [Networking](#networking) - [Development & Customization](#development--customization) + - [Local Serving & Image Configuration](#local-serving--image-configuration) - [Deploy to GitHub Pages](#deploy-to-github-pages) - - [Build Custom Disk Images](#building-custom-disk-images) - - [Run Locally](#run-webvm-locally) - [Example: Python3 REPL](#example-python3-repl) - [Features](#features) - [Claude AI Integration](#claude-ai-integration) @@ -40,26 +39,16 @@ WebVM is powered by the **CheerpX** virtualization engine, which provides: Visit [https://webvm.io](https://webvm.io) to get started immediately in your browser. No setup required. -### Local Development - -If you'd like to run WebVM locally: - -```sh -git clone https://github.com/leaningtech/webvm.git -cd webvm -npm install && npm run build -nginx -p . -c nginx.conf -``` - -Then open `http://127.0.0.1:8081` in your browser. - -For detailed local setup with custom images, see [Run Locally](#run-webvm-locally-with-a-custom-debian-mini-disk-image). +For local setup, custom image builds, and fork/deploy guidance, see [Development & Customization](#development--customization). ## Networking -Modern browsers don't provide TCP/UDP sockets directly. WebVM supports networking via **Tailscale**, a WireGuard-based VPN with WebSocket support. +WebVM now does something browsers usually cannot: it brings **Tailscale** networking into the VM itself, so your browser VM can reach your private network and, with an exit node, the public internet too. -### Quick Setup +> [!NOTE] +> Some low-level networking operations (especially ICMP used by `ping`) are not currently available in this environment. For connectivity checks, use `curl` or `wget`. + +### Local network 1. Open the "Networking" panel from the sidebar 2. Click "Connect to Tailscale" @@ -68,16 +57,9 @@ Modern browsers don't provide TCP/UDP sockets directly. WebVM supports networkin WebVM now has access to all machines in your Tailscale network! -## The world wide web - -If you would like to access the public internet, you will need to set up an Exit Node on one of your _non-WebVM_ tailscale network devices. -See the _"Advertise a device as an exit node"_ section of the [Tailscale Exit Node quickstart guide](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux) for instructions. (The _“Use an exit node”_ section can be skipped, as WebVM automatically uses an available exit node once one is advertised). - -> [!NOTE] -> Some commands like `ping` require kernel features unavailable in browsers. Use `curl` or `wget` instead. - > [!TIP] -> Connection status is shown as a colored dot on the button: orange = local network, green = global/internet. The button text shows your Tailscale IP address once connected. +> On slower connections there may be a short delay before initialisation. Connection status is shown as a colored dot on the button: orange = local network, green = global/internet. The button text shows your Tailscale IP address once connected. + ### Internet Access (Exit Node) @@ -86,16 +68,24 @@ To access the public internet from WebVM, set up an **Exit Node** on another dev 1. Follow the [Tailscale Exit Node quickstart](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux) (sections: "Advertise a device as an exit node") 2. WebVM automatically uses the exit node once advertised -### Authentication Options +### Using an Auth Key -**Via API key (for automation):** +As an alternative to interactive login, add your Tailscale auth key to the URL fragment: ``` https://webvm.io/#authKey= ``` -**Via Headscale (self-hosted Tailscale):** +This is equivalent to Tailscale's `--login-server` option. + +> [!TIP] +> If you also need a custom control server, add `controlUrl` in the same URL fragment and separate values with `&`, for example: `#authKey=...&controlUrl=...`. + +### Self-Hosting Tailscale with Headscale + +We also support [headscale](https://headscale.net/stable/), a selfhosted open source implementation of the Tailscale control server. +Because Headscale does not add CORS headers by default, you will need a proxy in front of it. See the [Headscale reverse proxy setup docs](https://headscale.net/stable/ref/integration/reverse-proxy/#nginx) for an example. -Headscale doesn't support CORS by default. Set up an Nginx proxy with CORS headers: +Once ready, add the following line to your `location /` block in your nginx config file. ```nginx if ($http_origin = "https://yourdomain.com") { @@ -109,154 +99,73 @@ Then access WebVM with: https://yourdomain.com/#controlUrl= ``` -See [Headscale Nginx integration docs](https://headscale.net/stable/ref/integration/reverse-proxy/#nginx) for more details. - -**Notes:** -- If self-hosting, replace URLs with your own domain -- This is equivalent to the Tailscale `--login-server` option -- When using both `authKey` and `controlUrl`, separate them with `&`: `#authKey=...&controlUrl=...` ## Development & Customization -### Deploy to GitHub Pages - -Fork the WebVM repository to deploy your own version to GitHub Pages: - -deploy_instructions_gif - -1. **Fork the repository** (click the Fork button on GitHub) -2. **Enable GitHub Pages:** - - Go to Settings → Pages - - Select "GitHub Actions" as the source - - Enable "Enforce HTTPS" if using a custom domain -3. **Run the Deploy workflow:** - - Go to Actions → Click "Deploy" workflow - - Click "Run workflow" twice (once in the dropdown menu) -4. After a few minutes, the workflow will show your deployed URL below the `deploy_to_github_pages` job - - - -### Building Custom Disk Images - -You can customize the Debian mini image or create entirely new disk images using the **Deploy workflow**. - -The workflow builds a custom Dockerfile into a bootable `.ext2` disk image and can either: -- **Upload to GitHub Release** — Download and use locally -- **Deploy to GitHub Pages** — Use remotely from your fork - -**To build a custom image:** - -1. Modify `dockerfiles/debian_mini` or create a new Dockerfile -2. Go to Actions → "Deploy" workflow → "Run workflow" -3. Set the "Path to Dockerfile" parameter to your Dockerfile -4. Choose deployment: "Upload as release" or "Deploy to pages" -5. After the workflow completes, download the `.ext2` file (from Releases tab if you chose "Upload as release") +### Local Serving & Image Configuration -**To use a custom image locally:** +If you are running WebVM locally, this is the primary flow. -1. Save the `.ext2` file to `custom-disk-images/` -2. In `config_public_terminal.js`, set: - ```js - diskImageUrl = "/custom-disk-images/your-image.ext2" - diskImageType = "bytes" - ``` -3. Rebuild: `npm install && npm run build` - -**For the full Alpine desktop environment:** - -Our Alpine/Xorg/i3 environment Dockerfile is available [here](https://github.com/leaningtech/alpine-image). - -**For more details:** - -See the [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). - -### Run WebVM Locally - -#### 1. Clone the WebVM Repository +#### 1. Clone the repository ```sh git clone https://github.com/leaningtech/webvm.git cd webvm ``` -#### 2. Put your local image in `custom-disk-images/` +#### 2. Put your image in `custom-disk-images/` This repository includes a persistent `custom-disk-images/` directory for local `.ext2` files. -Download the Debian mini image into that directory: +To use the official Debian mini image, download it from Releases: -```sh -wget -O custom-disk-images/debian_mini_20230519_5022088024.ext2 \ - "https://github.com/leaningtech/webvm/releases/download/ext2_image/debian_mini_20230519_5022088024.ext2" -``` +[debian_mini_20230519_5022088024.ext2](https://github.com/leaningtech/webvm/releases/download/ext2_image/debian_mini_20230519_5022088024.ext2) -(*You can also build your own image and copy it into `custom-disk-images/`.*) +You can also copy in an image you built yourself. -#### 3. Configure WebVM to use the local image +#### 3. Point WebVM to your local image Edit `config_public_terminal.js`: -- Set `diskImageUrl` to your local file URL, for example: - - `"/custom-disk-images/debian_mini_20230519_5022088024.ext2"` - -- Set `diskImageType` to: - - `"bytes"` - -#### 4. Build WebVM +```js +export const diskImageUrl = "/custom-disk-images/debian_mini_20230519_5022088024.ext2"; +export const diskImageType = "bytes"; +``` -Install dependencies and build: +#### 4. Install dependencies and build ```sh npm install npm run build ``` -The web assets are generated into `build/`. - -#### 5. Configure Nginx - -Keep your existing `location /` that serves `build/`, and add a separate location for custom images: - -```nginx -location /custom-disk-images/ { - alias ./custom-disk-images/; -} -``` - -Why this separate location is needed: - -- `location /` points to `build/`, but the image file lives outside `build/`. -- If you try to serve images only through `location /`, Nginx will look under `build/custom-disk-images/...`. -- Keeping images outside `build/` avoids losing them on future `npm run build` runs. - -`autoindex` is optional and not required for WebVM disk loading. It can stay off. - -#### 6. Start Nginx - -Run the following command to start Nginx: +#### 5. Start Nginx and open WebVM ```sh nginx -p . -c nginx.conf ``` -#### 7. Verify that the local image is actually being used +Then open `http://127.0.0.1:8081` and enjoy your local WebVM! + +### Deploy to GitHub Pages -In another shell, inspect access logs while loading WebVM: +Fork the WebVM repository to deploy your own version to GitHub Pages: -```sh -tail -f nginx_access.log | grep --line-buffered custom-disk-images -``` +deploy_instructions_gif + +1. **Fork the repository** +2. **Enable GitHub Pages** in Settings → Pages using "GitHub Actions" as source +3. **Run the `Deploy` workflow** from Actions +4. After completion, open the URL shown under the `deploy_to_github_pages` job -You should see repeated `206` responses for `/custom-disk-images/...ext2`. + -#### 8. Access WebVM +The same `Deploy` workflow also builds custom `.ext2` disk images from a Dockerfile. You can point it at `dockerfiles/debian_mini` or another Dockerfile, then either publish the result as a GitHub Release asset or deploy the Pages build from your fork. -Open a browser and visit: `http://127.0.0.1:8081`. +For the full Alpine desktop environment, see [leaningtech/alpine-image](https://github.com/leaningtech/alpine-image). -Enjoy your local WebVM! +For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). ### Example: Python3 REPL @@ -275,8 +184,6 @@ index 2878332..1f3103a 100644 +CMD [ "/usr/bin/python3" ] ``` -## Features - ### Claude AI Integration To access Claude AI, you need an API key. Follow these steps to get started: diff --git a/config_public_terminal.js b/config_public_terminal.js index 0d8cc8768..2c49d4a71 100644 --- a/config_public_terminal.js +++ b/config_public_terminal.js @@ -1,6 +1,6 @@ -// The root filesystem location +// The root OS image location, change to local filepath if serving locally export const diskImageUrl = "wss://disks.webvm.io/debian_large_20230522_5044875331_2.ext2"; -// The root filesystem backend type +// The root filesystem backend type use "cloud" for serving remotely or "bytes" for serving locally export const diskImageType = "cloud"; // Print an introduction message about the technology export const printIntro = true; diff --git a/nginx.conf b/nginx.conf index 6ab81c53b..b828a3677 100644 --- a/nginx.conf +++ b/nginx.conf @@ -32,8 +32,7 @@ http { server_name localhost; gzip on; - # Enable compression for .wasm, .js and .txt files (used for the runtime chunks) - gzip_types application/javascript application/wasm text/plain + gzip_types application/javascript application/wasm text/plain; charset utf-8; @@ -48,5 +47,8 @@ http { add_header 'Cross-Origin-Embedder-Policy' 'require-corp' always; add_header 'Cross-Origin-Resource-Policy' 'cross-origin' always; } + location /custom-disk-images/ { + root .; + } } } From e1c9d0d287fd607c24b98459c3de939470f27706 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 14:42:34 +0200 Subject: [PATCH 03/16] initial option for REPL rework- needs review --- README.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 387f1fc2b..c7583f113 100644 --- a/README.md +++ b/README.md @@ -169,19 +169,11 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d ### Example: Python3 REPL -The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy. - -```diff -diff --git a/dockerfiles/debian_mini b/dockerfiles/debian_mini -index 2878332..1f3103a 100644 ---- a/dockerfiles/debian_mini -+++ b/dockerfiles/debian_mini -@@ -15,4 +15,4 @@ WORKDIR /home/user/ - # We set env, as this gets extracted by Webvm. This is optional. - ENV HOME="/home/user" TERM="xterm" USER="user" SHELL="/bin/bash" EDITOR="vim" LANG="en_US.UTF-8" LC_ALL="C" - RUN echo 'root:password' | chpasswd --CMD [ "/bin/bash" ] -+CMD [ "/usr/bin/python3" ] +The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy: + +``` +Replace: CMD [ "/bin/bash" ] +With: CMD [ "/usr/bin/python3" ] ``` ### Claude AI Integration From e496f209d5ab61668e31c30d258efe7790c3b643 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:19:20 +0200 Subject: [PATCH 04/16] two options for REPL --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c7583f113..1d2d98010 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,14 @@ Replace: CMD [ "/bin/bash" ] With: CMD [ "/usr/bin/python3" ] ``` +> [!TIP] Python3 REPL +> +> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy: +> ``` +> Replace: CMD [ "/bin/bash" ] +> With: CMD [ "/usr/bin/python3" ] +> ``` + ### Claude AI Integration To access Claude AI, you need an API key. Follow these steps to get started: @@ -183,20 +191,13 @@ To access Claude AI, you need an API key. Follow these steps to get started: #### 1. Create an account - Visit [Anthropic Console](https://console.anthropic.com/login) and sign up with your e-mail. You'll receive a sign in link to the Anthropic Console. - - #### 2. Get your API key - Once logged in, navigate to **Get API keys**. - Purchase the amount of credits you need. After completing the purchase, you'll be able to generate the key through the API console. - - #### 3. Log in with your API key - Navigate to your WebVM and hover over the robot icon. This will show the Claude AI Integration tab. For added convenience, you can click the pin button in the top right corner to keep the tab in place. - You'll see a prompt where you can insert your Claude API key. -- Insert your key and press enter. - - #### 4. Start using Claude AI - Once your API key is entered, you can begin interacting with Claude AI by asking questions such as: From 981bb16b91a9e34e3b5a6169fcfc64075f6433cb Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:25:03 +0200 Subject: [PATCH 05/16] going with the 'tip' version and very simple cmd explanation for now --- README.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 1d2d98010..132b07710 100644 --- a/README.md +++ b/README.md @@ -167,22 +167,10 @@ For the full Alpine desktop environment, see [leaningtech/alpine-image](https:// For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). -### Example: Python3 REPL - -The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy: - -``` -Replace: CMD [ "/bin/bash" ] -With: CMD [ "/usr/bin/python3" ] -``` - -> [!TIP] Python3 REPL -> -> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply apply this patch and deploy: -> ``` -> Replace: CMD [ "/bin/bash" ] -> With: CMD [ "/usr/bin/python3" ] -> ``` +> [!TIP] +> Python3 REPL +> +> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. ### Claude AI Integration From 112091b265d47048170f1a74d8f462912e47e632 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:28:53 +0200 Subject: [PATCH 06/16] reviewing initial changes to REPL and claude --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 132b07710..c8d4ac7d8 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,8 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d > [!TIP] > Python3 REPL > -> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. +> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. +> To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. ### Claude AI Integration From aacdc79963d8630a5867069eea5754d48407d853 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:29:42 +0200 Subject: [PATCH 07/16] reviewing initial changes to REPL and claude --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index c8d4ac7d8..5059c3c1e 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,7 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d > Python3 REPL > > The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. +> > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. ### Claude AI Integration From c4a3f1aa7baa12b6bffd0970445d2914f0c4c0bd Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:30:19 +0200 Subject: [PATCH 08/16] reviewing initial changes to REPL and claude --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 5059c3c1e..5461016f8 100644 --- a/README.md +++ b/README.md @@ -168,9 +168,7 @@ For the full Alpine desktop environment, see [leaningtech/alpine-image](https:// For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). > [!TIP] -> Python3 REPL -> -> The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. +> Eample: Python3 REPL. The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. > > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. From 949d699716dad20aac49236c5ed78103c2fa29a5 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 15:31:24 +0200 Subject: [PATCH 09/16] typo and wording edit for REPL --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5461016f8..7d82e358e 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,7 @@ For the full Alpine desktop environment, see [leaningtech/alpine-image](https:// For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). > [!TIP] -> Eample: Python3 REPL. The `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. +> For Python3 REPL, the `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. > > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. From d147dc2901350df6db4636208f589b227b3d04cb Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 16:57:44 +0200 Subject: [PATCH 10/16] removed unnecessary REPL link from TOC, added Features header and fixed link to features section in TOC --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7d82e358e..b74b61ec8 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,7 @@ WebVM is powered by the **CheerpX** virtualization engine, which provides: - [Development & Customization](#development--customization) - [Local Serving & Image Configuration](#local-serving--image-configuration) - [Deploy to GitHub Pages](#deploy-to-github-pages) - - [Example: Python3 REPL](#example-python3-repl) -- [Features](#features) +- [Features](#freatures) - [Claude AI Integration](#claude-ai-integration) - [Community & Support](#community--support) - [Learn More](#learn-more) @@ -172,6 +171,8 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d > > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. +## Freatures + ### Claude AI Integration To access Claude AI, you need an API key. Follow these steps to get started: From 50b669e6f87217a3a963098706fc9803f8d26bc9 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 17:04:08 +0200 Subject: [PATCH 11/16] additional link to cheerpx licensing information --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b74b61ec8..50d9e6013 100644 --- a/README.md +++ b/README.md @@ -238,4 +238,4 @@ The public CheerpX deployment is provided **as-is** and is **free to use** for t Read more about [CheerpX licensing](https://cheerpx.io/docs/licensing) -If you want to build a product on top of CheerpX/WebVM, please get in touch: sales@leaningtech.com +If you want to build a product on top of CheerpX/WebVM, please see our other licensing options: https://cheerpx.io/licensing or get in touch: sales@leaningtech.com From 413c88b57645614d1368591cd6ede136c16941ac Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 17:06:51 +0200 Subject: [PATCH 12/16] prettier readme --- README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 50d9e6013..92f10fcd0 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Try out the new Alpine / Xorg / i3 graphical environment: [https://webvm.io/alpi WebVM is a server-less virtual environment running fully client-side in HTML5/WebAssembly. It's designed to be Linux ABI-compatible and runs an unmodified Debian distribution including many native development toolchains. WebVM is powered by the **CheerpX** virtualization engine, which provides: + - x86-to-WebAssembly JIT compiler - Virtual block-based file system - Linux syscall emulator @@ -59,7 +60,6 @@ WebVM now has access to all machines in your Tailscale network! > [!TIP] > On slower connections there may be a short delay before initialisation. Connection status is shown as a colored dot on the button: orange = local network, green = global/internet. The button text shows your Tailscale IP address once connected. - ### Internet Access (Exit Node) To access the public internet from WebVM, set up an **Exit Node** on another device in your Tailscale network: @@ -70,6 +70,7 @@ To access the public internet from WebVM, set up an **Exit Node** on another dev ### Using an Auth Key As an alternative to interactive login, add your Tailscale auth key to the URL fragment: + ``` https://webvm.io/#authKey= ``` @@ -94,12 +95,11 @@ if ($http_origin = "https://yourdomain.com") { ``` Then access WebVM with: + ``` https://yourdomain.com/#controlUrl= ``` - - ## Development & Customization ### Local Serving & Image Configuration @@ -128,7 +128,8 @@ You can also copy in an image you built yourself. Edit `config_public_terminal.js`: ```js -export const diskImageUrl = "/custom-disk-images/debian_mini_20230519_5022088024.ext2"; +export const diskImageUrl = + "/custom-disk-images/debian_mini_20230519_5022088024.ext2"; export const diskImageType = "bytes"; ``` @@ -167,7 +168,7 @@ For the full Alpine desktop environment, see [leaningtech/alpine-image](https:// For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/docs/guides/custom-images). > [!TIP] -> For Python3 REPL, the `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. +> For Python3 REPL, the `Deploy` workflow takes into account the `CMD` specified in the Dockerfile. > > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. @@ -178,20 +179,24 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d To access Claude AI, you need an API key. Follow these steps to get started: #### 1. Create an account -- Visit [Anthropic Console](https://console.anthropic.com/login) and sign up with your e-mail. You'll receive a sign in link to the Anthropic Console. + +- Visit [Anthropic Console](https://console.anthropic.com/login) and sign up with your e-mail. You'll receive a sign in link to the Anthropic Console. #### 2. Get your API key + - Once logged in, navigate to **Get API keys**. - Purchase the amount of credits you need. After completing the purchase, you'll be able to generate the key through the API console. #### 3. Log in with your API key + - Navigate to your WebVM and hover over the robot icon. This will show the Claude AI Integration tab. For added convenience, you can click the pin button in the top right corner to keep the tab in place. - You'll see a prompt where you can insert your Claude API key. #### 4. Start using Claude AI + - Once your API key is entered, you can begin interacting with Claude AI by asking questions such as: - __"Solve the CTF challenge at `/home/user/chall1.bin.` Note that the binary reads from stdin."__ +**"Solve the CTF challenge at `/home/user/chall1.bin.` Note that the binary reads from stdin."** deploy_instructions_gif @@ -206,17 +211,20 @@ To access Claude AI, you need an API key. Follow these steps to get started: ## Learn More **Articles & Resources:** + - [WebVM: Server-less x86 virtual machines in the browser](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) - [WebVM: Linux Virtualization in WebAssembly with Full Networking via Tailscale](https://leaningtech.com/webvm-virtual-machine-with-networking-via-tailscale/) - [Mini.WebVM: Your own Linux box from Dockerfile, virtualized in the browser via WebAssembly](https://leaningtech.com/mini-webvm-your-linux-box-from-dockerfile-via-wasm/) - [Crafting the Impossible: X86 Virtualization in the Browser with WebAssembly](https://www.youtube.com/watch?v=VqrbVycTXmw) — Talk at JsNation 2022 **Example Deployment:** + - [Mini.WebVM Reference](https://mini.webvm.io) — A running example deployed to GitHub Pages **Technology Behind WebVM:** This project is powered by: + - **[CheerpX](https://cheerpx.io/)** — x86-to-WebAssembly JIT compiler | by [Leaning Technologies](https://leaningtech.com/) - **[xterm.js](https://xtermjs.org/)** — Web-based terminal emulator - **[Tailscale](https://tailscale.com/)** — VPN networking layer From e99525288a383f5340dd83ab144630bbc4e7d37f Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 17:27:50 +0200 Subject: [PATCH 13/16] fixed cheerpx licensing link, changed above link name so it doesnt look like the same page is linked twice --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 92f10fcd0..8cc6c75b5 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,6 @@ You are welcome to use, modify, and redistribute the contents of this repository The public CheerpX deployment is provided **as-is** and is **free to use** for technological exploration, testing and use by individuals. Any other use by organizations, including non-profit, academia and the public sector, requires a license. Downloading a CheerpX build for the purpose of hosting it elsewhere is not permitted without a commercial license. -Read more about [CheerpX licensing](https://cheerpx.io/docs/licensing) +Read more about [CheerpX licensing.](https://cheerpx.io/docs/licensing) -If you want to build a product on top of CheerpX/WebVM, please see our other licensing options: https://cheerpx.io/licensing or get in touch: sales@leaningtech.com +If you want to build a product on top of CheerpX/WebVM, please see our other licensing options: [CheerpX licensing](https://cheerpx.io/licensing) or get in touch: sales@leaningtech.com From 33f62bd02fade2245b3265aacbba7fc21e6aab4f Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 21 Apr 2026 17:27:59 +0200 Subject: [PATCH 14/16] fixed cheerpx licensing link, changed above link name so it doesnt look like the same page is linked twice --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8cc6c75b5..2823d99f5 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,6 @@ You are welcome to use, modify, and redistribute the contents of this repository The public CheerpX deployment is provided **as-is** and is **free to use** for technological exploration, testing and use by individuals. Any other use by organizations, including non-profit, academia and the public sector, requires a license. Downloading a CheerpX build for the purpose of hosting it elsewhere is not permitted without a commercial license. -Read more about [CheerpX licensing.](https://cheerpx.io/docs/licensing) +Read more [here](https://cheerpx.io/docs/licensing) about our licensing practices. If you want to build a product on top of CheerpX/WebVM, please see our other licensing options: [CheerpX licensing](https://cheerpx.io/licensing) or get in touch: sales@leaningtech.com From 18307a90c403be2c7059e25ad5d01833a4dc876a Mon Sep 17 00:00:00 2001 From: Sarah McLacken <115113929+smclacke@users.noreply.github.com> Date: Tue, 28 Apr 2026 16:14:00 +0200 Subject: [PATCH 15/16] Update README.md Co-authored-by: Merlin de Cloe <89702955+codingfrog27@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2823d99f5..5e5aa30f4 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ For local setup, custom image builds, and fork/deploy guidance, see [Development ## Networking -WebVM now does something browsers usually cannot: it brings **Tailscale** networking into the VM itself, so your browser VM can reach your private network and, with an exit node, the public internet too. +WebVM supports **Tailscale** integration. So your browser VM can reach your private network and, with an exit node, the public internet too. > [!NOTE] > Some low-level networking operations (especially ICMP used by `ping`) are not currently available in this environment. For connectivity checks, use `curl` or `wget`. From 80aa9816e424ce658db8cab7e3996086f4a044f2 Mon Sep 17 00:00:00 2001 From: smclacke Date: Tue, 28 Apr 2026 16:28:20 +0200 Subject: [PATCH 16/16] resolving Merlin comments from open PR, i've left comments too for each small change --- README.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2823d99f5..271ad62f0 100644 --- a/README.md +++ b/README.md @@ -22,24 +22,19 @@ WebVM is powered by the **CheerpX** virtualization engine, which provides: ## Table of Contents -- [Quick Start](#quick-start) - [Networking](#networking) - [Development & Customization](#development--customization) - [Local Serving & Image Configuration](#local-serving--image-configuration) - [Deploy to GitHub Pages](#deploy-to-github-pages) -- [Features](#freatures) - - [Claude AI Integration](#claude-ai-integration) +- [Claude AI Integration](#claude-ai-integration) - [Community & Support](#community--support) - [Learn More](#learn-more) - [License](#license) -## Quick Start - -### Online (No Installation) - -Visit [https://webvm.io](https://webvm.io) to get started immediately in your browser. No setup required. - -For local setup, custom image builds, and fork/deploy guidance, see [Development & Customization](#development--customization). +> [!NOTE] +> Visit [https://webvm.io](https://webvm.io) to get started immediately in your browser. No setup required. +> +> For local setup, custom image builds, and fork/deploy guidance, see [Development & Customization](#development--customization). ## Networking @@ -56,12 +51,12 @@ WebVM now does something browsers usually cannot: it brings **Tailscale** networ 4. Click "Connect" when prompted WebVM now has access to all machines in your Tailscale network! + +### Internet Usage Tips > [!TIP] > On slower connections there may be a short delay before initialisation. Connection status is shown as a colored dot on the button: orange = local network, green = global/internet. The button text shows your Tailscale IP address once connected. -### Internet Access (Exit Node) - To access the public internet from WebVM, set up an **Exit Node** on another device in your Tailscale network: 1. Follow the [Tailscale Exit Node quickstart](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux) (sections: "Advertise a device as an exit node") @@ -104,8 +99,6 @@ https://yourdomain.com/#controlUrl= ### Local Serving & Image Configuration -If you are running WebVM locally, this is the primary flow. - #### 1. Clone the repository ```sh @@ -172,9 +165,7 @@ For more details, see [CheerpX Custom Images documentation](https://cheerpx.io/d > > To build a REPL you can simply change `CMD [ "/bin/bash" ]` to `CMD [ "/usr/bin/python3" ]` and deploy. -## Freatures - -### Claude AI Integration +## Claude AI Integration To access Claude AI, you need an API key. Follow these steps to get started: