webvm/README.md

WebVM

This repository hosts the source code for https://webvm.io, a Linux virtual machine that runs in your browser.

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.

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.

Enable networking

• Click "Connect via Tailscale" in the page header.
• Log in to Tailscale (create an account if you don't have one).
• If you are unfamiliar with Tailscale or would like additional information see WebVM and Tailscale.

Fork, deploy, customize

• Fork the repository.
• Enable Github pages in settings.
  • Click on Settings.
  • Go to the Pages section.
  • Select Github Actions as the source.
• 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.
• Customize dockerfiles/debian_mini to suits your needs.
• You can also make a new Dockerfile from scratch. Use the "Path to Dockerfile" workflow parameter to select it.

After the workflow completes, which takes a few minutes, it will show the URL below the deploy_to_github_pages job.

Local deployment

From a local git clone

• Download the debian_mini Ext2 image from https://github.com/leaningtech/webvm/releases/
  • You can also build your own by selecting the "Upload GitHub release" workflow option.
  • Place the image in the repository root folder.
• Edit index.html
  • Replace the UID/GID variables with 1000
  • Replace DEVICE_TYPE with "bytes"
  • Replace IMAGE_URL with the name of the Ext2 image. For example "debian_mini_20230519_5022088024.ext2"
• Start a local HTTP server
• Enjoy your local WebVM.

Bugs and Issues

Please use Issues to report any bug. Or come to say hello / share your feedback on Discord.

More links

• WebVM: server-less x86 virtual machines in the browser
• WebVM: Linux Virtualization in WebAssembly with Full Networking via Tailscale
• Reference GitHub Pages deployment: Mini.WebVM
• Crafting the Impossible: X86 Virtualization in the Browser with WebAssembly Talk at JsNation 2022

Thanks to...

This project depends on:

• CheerpX, made by Leaning Technologies for x86 virtualization and Linux emulation
• xterm.js, https://xtermjs.org/, for providing the Web-based terminal emulator
• Tailscale for the networking component
• lwIP for the TCP/IP stack, compiled for the Web via Cheerp

License

Copyright (c) Leaning Technologies Limited. All rights reserved.