webvm README

The project's README from github.com/leaningtech/webvm. As one markdown file: README.md.

WebVM

Discord server Issues

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

Try out the new Alpine / Xorg / i3 graphical environment: https://webvm.io/alpine.html

What is WebVM?

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:

Table of Contents

[!NOTE] Visit 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.

Networking

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.

Local network

  1. Open the "Networking" panel from the sidebar
  2. Click "Connect to Tailscale"
  3. Log in (create a free account at tailscale.com if needed)
  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.

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 (sections: "Advertise a device as an exit node")
  2. WebVM automatically uses the exit node once advertised

Using an Auth Key

As an alternative to interactive login, add your Tailscale auth key to the URL fragment:

https://webvm.io/#authKey=<your-ephemeral-key>

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, 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 for an example.

Once ready, add the following line to your location / block in your nginx config file.

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=<your-headscale-url>

Development & Customization

[!NOTE] Users have root privileges by default. sudo is not installed though this can easily be added to the Dockerfile if needed.

Deploy to GitHub Pages

This is a simple, beginner-friendly workflow. For local hosting and customization, see below Local Serving & Image Configuration.

Fork the WebVM repository to deploy your own version to GitHub Pages:

deploy_instructions_gif
  1. Fork the repository
  2. Enable GitHub Pages via forked repository 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

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.

[!NOTE] dockerfiles/debian_large is too large of an image for GitHub pages.

Local Serving & Image Configuration

1. Clone the repository

git clone https://github.com/leaningtech/webvm.git
cd webvm

2. Put your image in custom-disk-images/

This repository includes a persistent custom-disk-images/ directory for local .ext2 files.

To use the official Debian mini image, download it from Releases:

debian_mini_20230519_5022088024.ext2

You can also copy in an image you built yourself.

3. Point WebVM to your local image

Edit config_public_terminal.js:

export const diskImageUrl =
  "/custom-disk-images/debian_mini_20230519_5022088024.ext2";
export const diskImageType = "bytes";

4. Install dependencies and build

npm install
npm run build

5. Start Nginx and open WebVM

nginx -p . -c nginx.conf

Then open http://127.0.0.1:8081 and enjoy your local WebVM!

For the full Alpine desktop environment, see leaningtech/alpine-image.

For more details, see CheerpX Custom Images documentation.

[!TIP] 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.

Claude AI Integration

To access Claude AI, you need an API key. Follow these steps to get started:

1. Create an account

2. Get your API key

3. Log in with your API key

4. Start using Claude AI

"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, it is only stored locally in your browser.

Community & Support

Report issues: Use GitHub Issues to report bugs or request features.

Chat with us: Join our Discord community to discuss WebVM, share ideas, and get help.

Learn More

Articles & Resources:

Example Deployment:

Technology Behind WebVM:

This project is powered by:

Versioning:

WebVM uses the 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.

License

WebVM is released under the Apache License, Version 2.0.

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 here about our licensing practices.

If you want to build a product on top of CheerpX/WebVM, please see our other licensing options: CheerpX licensing or get in touch: [email protected]

webvm (leaningtech/webvm)

Searching Database…

17.4K ·GitHub
Webvm
Что это такое?WebVM — это виртуальная машина с Linux, которая работает целиком в вашем браузере: немодифицированный дистрибутив Debian с нативными инструментами разработки, полностью на стороне клиента, без установки и без сервера.
То есть вся виртуалка правда работает на моём компьютере, а не на удалённом сервере?Да — движок CheerpX выполняет JIT-компиляцию из x86 в WebAssembly, эмулирует системные вызовы Linux и предоставляет виртуальную блочную файловую систему, и всё это в песочнице внутри вкладки браузера.
Как мне это попробовать?Откройте размещённый сайт WebVM в браузере — ничего настраивать не нужно. Для собственной копии сделайте форк репозитория и запустите workflow Deploy, чтобы опубликовать её на GitHub Pages, либо раздайте локальный образ через nginx.
Встроенной интеграции с Claude AI нужен API-ключ Anthropic?Да — вы вставляете свой API-ключ во вкладку с иконкой робота, и он остаётся у вас: он хранится только локально в вашем браузере, у команды WebVM к нему доступа нет.
Может ли виртуалка выйти в интернет из моего браузера?Только через Tailscale: подключитесь через панель Networking, чтобы попасть в свою приватную сеть, а для выхода в публичный интернет нужен exit node на другом устройстве. ICMP/ping недоступен — используйте curl или wget.
И правда бесплатно пользоваться?Код репозитория под лицензией Apache-2.0, и частные лица могут бесплатно пользоваться публичным развёртыванием CheerpX, но любое использование организацией — даже некоммерческое или в учёных целях — требует лицензии, а перепубликация CheerpX — коммерческой.
Там только терминал, или есть и графический рабочий стол?Образ Debian по умолчанию работает только в терминале, но есть более новый графический вариант на Alpine / Xorg / i3, который можно попробовать: полноценный рабочий стол прямо в браузере.
Можно сделать из него Python REPL вместо оболочки bash?Да — поменяйте в Dockerfile команду CMD с /bin/bash на /usr/bin/python3 и разверните проект; workflow Deploy это учтёт и даст вам Python REPL в браузере.
Что там под капотом?CheerpX — JIT-компилятор из x86 в WebAssembly от Leaning Technologies; xterm.js для интерфейса терминала; lwIP в качестве TCP/IP-стека, скомпилированного для веба; и Tailscale для сетевого уровня.
What are similar projects?quicksand, ProxmoxVE, coop, nvx, qemu, ServerBox, ra2, smolvm
Which topics is it in?repl, tailscale, debian, vm, x86, virtual-machine, svelte, webassembly, emulator, virtualization, sandbox, wasm
Creator
leaningtech
Size
41.3 MB
Stars
17.4K
Updated
CommitOct 07Releaseext2_imageMay 16
Age
4y
Commits · 90 Days