This fork of copy/v86 adds two more machines to v86: a 64-bit ARM (AArch64) computer and a RISC-V computer (64- and 32-bit). Both boot real Linux images built with Buildroot, with a serial console, a virtual disk and networking, entirely client-side. The x86 emulator below is upstream's and unchanged.
Try them: landing page · ARM64 · RISC-V
ARM64 (AArch64): an ARMv8-A CPU on a QEMU virt-like machine (GIC,
PL011 UART, virtio disk, network and input, a framebuffer), with a JIT that
compiles hot code to WebAssembly. It runs:
- Buildroot Linux (ext4 and squashfs)
- OpenWrt 24.10 with the LuCI web interface
- U-Boot booting Linux from the disk
- An X11 desktop: openbox, xterm, an on-screen keyboard
The ARM site also has Pebble watches running
PebbleOS on a new Cortex-M core
(Cortex-M4 and Cortex-M33, Thumb-2, src/cm), on the emulator
boards PebbleOS's own emulator provides:
the Pebble 2 Duo,
with its display and four buttons, and
the round Pebble Round 2,
with its colour display, buttons and touch screen. The same core runs
the card10 badge
from the Chaos Communication Camp 2019: its MAX32666's two Cortex-M4F
cores, Epicardium (FreeRTOS) on one and Pycardium (MicroPython) on the
other, calling each other through shared memory and the chip's hardware
semaphores, with its display, buttons and MicroPython's REPL.
RISC-V (RV64GC and RV32GC): a hart with machine, supervisor and user modes, Sv39 and Sv32 paging, CLINT, PLIC, a 16550 UART and virtio devices, started by OpenSBI. It passes the riscv-tests ISA suites, is checked instruction by instruction against QEMU, and has a JIT. It runs:
- Buildroot Linux, riscv64 and riscv32
- Tetris on a WCH CH32V003 microcontroller (RV32EC, 2 KB of RAM), with touch controls on phones
- Stefan Wagner's CH32V003 Mini Game Console (source), with its OLED display, buttons and buzzer, and twelve games, among them Tiny Doom
- Maksym Curul's CH32V003 Mini Game Console (source), with its colour ST7735 LCD, buttons and buzzer: Snake, Pong, Jump Bird and Dino Run, with high scores saved in its flash
- Vlad Tomoiagă's osillyscope (source), a CH32V003 pocket oscilloscope built with ch32fun: its ADC sampling into DMA, triggered by the analog watchdog, fed a test signal or your microphone
- The RT-Thread shell on a WCH CH32V307 (RV32IMAFC)
Debugging in the browser: both sites have an image that runs
gdb-wui, a web UI for GDB, inside
the guest next to the console (ARM64,
RISC-V). Its Decompiled
view uses kuna, run as WebAssembly by the
page. The RISC-V core also has a GDB stub, so adding &debug to a CH32V003
page (Tetris,
the mini game console,
the oscilloscope, where a breakpoint
in its ADC watchdog's interrupt handler stops it at the trigger)
debugs the microcontroller's firmware in gdb-wui: breakpoints in flash,
stepping through the C source, registers and monitor reset halt.
Where things are:
| Path | Contents |
|---|---|
src/a64, src/a64_cpu.js |
The AArch64 core (Rust, built to build/v86-a64.wasm) and its glue |
src/rv64, src/rv64_cpu.js |
The RISC-V core and the CH32V microcontrollers (build/v86-rv64.wasm) |
tools/a64-site, tools/rv64-site, tools/landing-site |
The three websites (Cloudflare Workers) and the scripts that build their images |
src/cm, src/cm_cpu.js |
The Cortex-M core (build/v86-cm.wasm), for the Pebble watches and the card10 badge |
tools/gdb-wui-guest, tools/kuna-web |
gdb-wui in the guest, and kuna for the page |
tests/a64, tests/rv64, tests/guest-web |
Boot, microcontroller and page tests |
Each core's README (AArch64, RISC-V) covers building and testing it.
Branches: ports is the
fork's main branch, with both ports and all three sites; master mirrors
upstream.
The ports were written with Claude Opus 5.5 (Anthropic's model) in Claude Code. The original v86 and its x86 emulation are the work of the upstream project's authors; the rest of this README is upstream's.
v86 emulates an x86-compatible CPU and hardware. Machine code is translated to WebAssembly modules at runtime in order to achieve decent performance. Here's a list of emulated hardware:
- An x86-compatible CPU. The instruction set is around Pentium 4 level,
including full SSE3 support. Some features are missing, in particular:
- Task gates, far calls in protected mode
- Some 16 bit protected mode features
- Single stepping (trap flag, debug registers)
- Some exceptions, especially floating point and SSE
- Multicore
- 64-bit extensions
- A floating point unit (FPU). Calculations are done using the Berkeley SoftFloat library and therefore should be precise (but slow). Trigonometric and log functions are emulated using 64-bit floats and may be less precise. Not all FPU exceptions are supported.
- A floppy disk controller (8272A).
- An 8042 Keyboard Controller, PS2. With mouse support.
- An 8254 Programmable Interval Timer (PIT).
- An 8259 Programmable Interrupt Controller (PIC).
- Partial APIC support.
- A CMOS Real Time Clock (RTC).
- A generic VGA card with SVGA support and Bochs VBE Extensions.
- A PCI bus. This one is partly incomplete and not used by every device.
- An IDE disk controller.
- A built-in ISO 9660 CD-ROM generator with Joliet support.
- An NE2000 (RTL8390) PCI network card.
- Various virtio devices: Filesystem, network and balloon.
- A SoundBlaster 16 sound card.
- A hayes-compatible dial-up Modem.
9front — Arch Linux — Android-x86 1.6-r2 — Android-x86 4.4-r2 — BasicLinux — Buildroot Linux — Damn Small Linux — ELKS — FreeDOS — FreeBSD — FiwixOS — Haiku — SkiffOS — ReactOS — Windows 2000 — Windows 98 — Windows 95 — Windows 1.01 — MS-DOS 6.22 — OpenBSD — Oberon — KolibriOS — SkiftOS — QNX
How it works — Networking — Dial-up modem networking — Alpine Linux guest setup — Arch Linux guest setup — Debian with xfce guest setup — MS-DOS/FreeDOS guest setup — Windows 3.1x guest setup — Windows 9x guest setup — Windows NT guest setup — 9p filesystem — Linux rootfs on 9p — Profiling
Here's an overview of the operating systems supported in v86:
- Linux works pretty well. 64-bit kernels are not supported.
- Buildroot can be used to build a minimal image. humphd/browser-vm and darin755/browser-buildroot have some useful scripts for building one.
- SkiffOS (based on Buildroot) can cross-compile a custom image.
- Ubuntu and other Debian derivatives works up to the latest version that supported i386 (16.04 LTS or 18.04 LTS for some variants).
- Alpine Linux works. An image can be built from a Dockerfile, see tools/docker/alpine/.
- Arch Linux 32 works. See archlinux.md for building an image.
- ReactOS works.
- FreeDOS, Windows 1.01 and MS-DOS run very well.
- KolibriOS works.
- Haiku works.
- Android-x86 has been tested up to 4.4-r2.
- Windows 1, 3.x, 95, 98, ME, NT and 2000 work reasonably well.
- Windows XP, Vista and 8 work under certain conditions (see #86, #208)
- Many hobby operating systems work.
- 9front works.
- Plan 9 doesn't work.
- QNX works.
- OS/2 doesn't work.
- FreeBSD works.
- OpenBSD works with a specific boot configuration. At the
boot>prompt typeboot -c, then at theUKC>promptdisable mpbiosandexit. - NetBSD works only with a custom kernel, see #350.
- SerenityOS works (only 32-bit versions).
- SkiftOS works.
You can get some information on the disk images here: https://github.com/copy/images.
You need:
- make
- Rust with the wasm32-unknown-unknown target
- A version of clang compatible with Rust
- java (for Closure Compiler, not necessary when using
debug.html) - nodejs (a recent version is required, v24.16 is known to be working)
- To run tests: nasm, gdb, qemu-system, gcc, libc-i386 and rustfmt
See tools/docker/test-image/Dockerfile for a full setup on Debian or WSL.
-
Run
maketo build the debug build (atdebug.html). -
Run
make allto build the optimized build (atindex.html). -
ROM and disk images are loaded via XHR, so if you want to try out
index.htmllocally, make sure to serve it from a local webserver. You can usemake runto serve the files using Python's http module. -
If you only want to embed v86 in a webpage you can use
libv86.js. For usage, check out the examples. You can download it from the release section. -
For bundler-based setups (Vite/React/Next/Webpack), there is also an official npm package: https://www.npmjs.com/package/v86
This package was originally maintained by @giulioz (bundler-optimized fork) and was made "official" for this repo by @basicer with the author's permission. It is published automatically from this repository via GitHub Actions (.github/workflows/ci.yml, Upload release job) on pushes to
masterand usesnpm publish --provenance.Install:
npm install v86
- If you have Docker installed, you can run the whole system inside a container.
- See
tools/docker/execto find the Dockerfile required for this. - You can run
docker build -f tools/docker/exec/Dockerfile -t v86:alpine-3.19 .from the root directory to generate docker image. - Then you can simply run
docker run -it -p 8000:8000 v86:alpine-3.19to start the server. - Check
localhost:8000for hosted server.
- If you are using an IDE that supports Dev Containers, such as GitHub Codespaces, the Visual Studio Code Remote Container extension, or possibly others such as Jetbrains' IntelliJ IDEA, you can setup the development environment in a Dev Container.
- Follow the instructions from your development environment to setup the container.
- Run the Task "Fetch images" in order to download images for testing.
The disk images for testing are not included in this repository. You can download them directly from the website using:
mkdir -p images && curl --compressed --output-dir images/ --remote-name-all https://i.copy.sh/{linux.iso,linux3.iso,linux4.iso,buildroot-bzimage68.bin,TinyCore-11.0.iso,oberon.img,msdos.img,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.img,mobius-fd-release5.img,msdos622.img}
Run integration tests: make tests
Run all tests: make jshint rustfmt kvm-unit-test nasmtests nasmtests-force-jit expect-tests jitpagingtests qemutests rust-test tests
See tests/Readme.md for more information.
- Basic
- Programmatically using the serial terminal
- A Lua interpreter
- Two instances in one window
- Networking between browser windows/tabs using the Broadcast Channel API
- TCP Terminal (fetch-based networking)
- Saving and restoring emulator state
Using v86 for your own purposes is as easy as:
var emulator = new V86({
screen_container: document.getElementById("screen_container"),
bios: {
url: "../../bios/seabios.bin",
},
vga_bios: {
url: "../../bios/vgabios.bin",
},
cdrom: {
url: "../../images/linux.iso",
},
autostart: true,
});See v86.d.ts for TypeScript definitions. You can use make doc (TypeDoc) or make denodoc (Deno) to generate HTML documentation in ./docs/api/.
At this time, v86 does not accept pull requests or issues written partially or entirely by generative AI tools. Exceptions may be made on a case-by-case basis.
v86 is distributed under the terms of the Simplified BSD License, see LICENSE. The following third-party dependencies are included in the repository under their own licenses:
lib/softfloat/softfloat.clib/zstd/zstddeclib.ctests/kvm-unit-tests/tests/qemutests/src/floppy.js/contains parts ported from qemu under the MIT license, see LICENSE.MIT.
- CPU test cases via QEMU
- More tests via kvm-unit-tests
- zstd support is included for better compression of state images
- Berkeley SoftFloat is included to precisely emulate 80-bit floating point numbers
- The jor1k project for 9p, filesystem and uart drivers
- WinWorld sources of some old operating systems
- OS/2 Museum sources of some old operating systems
- ArchiveOS sources of several operating systems
Shoot me an email to copy@copy.sh. Please report bugs on GitHub.