x86-native is a cross-platform native Rust library for building x86 machine hosts without a browser, DOM, WebAssembly runtime or web frontend. The package name on crates.io is x86-native; the Rust library target remains x86, so applications use use x86::....

Project status: the native interpreter, saved-state restore, VirtIO-9P transport, host-directory filesystem, VGA framebuffer extraction and PS/2 text input are implemented and tested. The Arch saved state reaches the restored root@localhost:~# shell; dump-screen captures the guest framebuffer and type sends keyboard text. The project is still an incremental native device port, not a claim that every optional upstream v86 peripheral is already implemented.

The documentation index contains the API map, examples, architecture diagrams, console screenshots and release notes.

Add the package to your application:

[dependencies]
x86-native = "0.1"

Then import the library target as x86:

use x86::{Image, ImageKind, Machine, MachineConfig};

fn main() -> x86::Result<()> {
    let mut machine = Machine::new(
        MachineConfig::default().with_ram_bytes(512 * 1024 * 1024),
    );

    machine.set_disk(Image::from_file(ImageKind::RawDisk, "disk.img")?)?;
    println!("machine status: {:?}", machine.status());
    Ok(())
}

The package is designed for stable Rust and native targets supported by Cargo. Run cargo add x86-native or edit Cargo.toml manually as shown above.

For a strictly offline build:

cargo build --no-default-features

The Image type represents BIOS, VGA BIOS, raw disks, ISO images, kernels, initrds, bootloaders and memory-backed resources. It supports local file loading, SHA-256 calculation and checksum verification.

Resource and Bootloader provide a single interface for local paths, in-memory bytes and optional HTTP(S) URLs. SavedState validates v86-compatible state headers, metadata, buffer counts, memory size and compressed state data.

MachineConfig describes RAM, VGA memory, CPU frequency hints, command line and console mode. Machine attaches the machine resources and exposes prepare, run and stop. ExecutionBackend is a platform-neutral trait for connecting the actual native CPU/device engine.

use x86::{Bootloader, Image, ImageKind, Machine, MachineConfig, Resource, SavedState};

fn main() -> x86::Result<()> {
    let mut machine = Machine::new(
        MachineConfig::default()
            .with_ram_bytes(512 * 1024 * 1024)
            .with_command_line("rw console=ttyS0"),
    );

    machine.set_bios(Image::from_file(ImageKind::Bios, "seabios.bin")?)?;
    machine.set_vga_bios(Image::from_file(ImageKind::VgaBios, "vgabios.bin")?)?;
    machine.set_disk(Image::from_file(ImageKind::RawDisk, "disk.img")?)?;
    machine.set_saved_state(SavedState::from_file("state.bin.zst")?);
    machine.set_bootloader(Bootloader::load(Resource::url(
        "https://example.org/bootloader.bin",
    ))?);

    println!("state: {:?}", machine.status());
    Ok(())
}

Build and launch the terminal application:

cargo run --bin x86-console

The console is a normal native process. It does not start a web server or require a browser:

x86> load bios seabios.bin
x86> load vga-bios vgabios.bin
x86> load disk disk.img
x86> load state arch_state-v3.bin.zst
x86> load bootloader https://example.org/bootloader.bin
x86> info
x86> load state ./image/arch_state-v3.bin.zst
x86> run-state 1000000
x86> dump-screen ./arch-screen.ppm
x86> type echo native-ok
x86> run-state 1000000
x86> dump-screen ./arch-screen-after-input.ppm
x86> quit

The native console also supports run-state, dump-screen <path.ppm> and type <text>. dump-screen writes a standard PPM framebuffer that can be opened by macOS Preview, ImageMagick or converted to PNG; type injects PC AT keyboard scancodes and appends Enter. prepare and run return a typed BackendUnavailable error until an ExecutionBackend is attached. This is intentional: the library never reports a guest as running when no CPU/device backend exists.

The source diagram is available as docs/assets/architecture.mmd. The host layer is platform-neutral; platform-specific console, filesystem and networking adapters remain outside the core API.

The GitHub Releases page contains versioned native artifacts and source packages. The release workflow is configured to build Linux, macOS Intel, macOS Apple Silicon and Windows artifacts when a version tag is pushed.

git clone https://github.com/illussioon/x86.git
cd x86
cargo check
cargo test
cargo package
cargo run --bin x86-console

For native release builds:

cargo build --release

Licensed under either of BSD-2-Clause or MIT, at your option.

The API follows standard Cargo package conventions 1 and uses the repository's native Rust implementation as the source of truth 2.