{"id":13508909,"url":"https://github.com/humphd/browser-vm","last_synced_at":"2025-10-25T18:03:37.056Z","repository":{"id":50758441,"uuid":"169488899","full_name":"humphd/browser-vm","owner":"humphd","description":"A small Linux x86 VM meant for use in the browser","archived":false,"fork":false,"pushed_at":"2023-05-27T08:55:34.000Z","size":95,"stargazers_count":176,"open_issues_count":9,"forks_count":44,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-06T15:52:15.619Z","etag":null,"topics":["browser","buildroot","docker","vm","x86"],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/humphd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-06T22:50:15.000Z","updated_at":"2024-11-08T14:54:51.000Z","dependencies_parsed_at":"2024-06-20T13:00:53.938Z","dependency_job_id":"7e5564d8-178b-46eb-b96a-78b947aaba79","html_url":"https://github.com/humphd/browser-vm","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humphd%2Fbrowser-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humphd%2Fbrowser-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humphd%2Fbrowser-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humphd%2Fbrowser-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/humphd","download_url":"https://codeload.github.com/humphd/browser-vm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230382858,"owners_count":18216854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","buildroot","docker","vm","x86"],"created_at":"2024-08-01T02:01:00.337Z","updated_at":"2025-10-25T18:03:36.995Z","avatar_url":"https://github.com/humphd.png","language":"Dockerfile","funding_links":[],"categories":["Dockerfile","browser"],"sub_categories":[],"readme":"# Browser VM\n\nA custom [Buildroot](https://buildroot.org/) config for a Linux x86 VM, meant to\nbe run in the browser as part of [browser-shell](https://github.com/humphd/browser-shell).\nThe resulting Linux ISO is meant to be run under\nemulation in the browser via [v86](https://github.com/copy/v86), and includes:\n\n* a custom Linux 4.15 kernel, which strips out many unnecessary drivers, modules, etc. and adds [Plan 9 filesystem](https://www.kernel.org/doc/Documentation/filesystems/9p.txt) sharing\n* a root filesystem and Unix commands via [BusyBox](https://busybox.net/)\n* an ISO-based bootloader (i.e., we create a \"DVD\" that is booted by v86)\n\nFollowing the [Buildroot customization docs](https://buildroot.org/downloads/manual/manual.html#customize)\nwe create a folder `buildroot-v86/` with all the necessary config files,\nfilesystem overlay, and scripts necessary to build our distribution.\n\n## Running via Docker\n\nTo build the Docker image use the `build.sh` script, or:\n\n```bash\n$ docker build -t buildroot .\n```\n\nAnd then to run the build:\n\n```bash\n$ docker run \\\n    --rm \\\n    --name build-v86 \\\n    -v $PWD/dist:/build \\\n    -v $PWD/buildroot-v86/:/buildroot-v86 \\\n    buildroot\n```\n\nNOTE: we define two [volumes](https://docs.docker.com/engine/reference/builder/#volume) to \nallow the container to access the v86 config, and also to write the ISO once complete.  In the\nabove I've used `$PWD`, but you can use any absolute path.\n\nWhen the build completes, an ISO file will be places in `./dist/v86-linux.iso`\nin your source tree (i.e., outside the container).\n\nIf you need to re-configure things, instead of just running the build, do the following:\n\n```bash\n$ docker run \\\n    --rm \\\n    --name build-v86 \\\n    -v $PWD/dist:/build \\\n    -v $PWD/buildroot-v86/:/buildroot-v86 \\\n    -ti \\\n    --entrypoint \"bash\" \\\n    buildroot\n```\n\nNow in the resulting bash terminal, you can run `make menuconfig` and [other make commands](https://buildroot.org/downloads/manual/manual.html#make-tips).\n\n## `buildroot-v86/` Layout\n\nWe define a `v86` buildroot \"board\" via the following files and directories:\n\n```\n+-- board/\n    +-- v86\n        +-- linux.config        # our custom Linux kernel config (make linux-menuconfig)\n        +-- post_build.sh       # script to copy ISO file out of docker container\n        +-- rootfs_overlay/     # overrides for files in the root filesystem\n            +-- etc/\n                +-- inittab     # we setup a ttyS0 console terminal to auto-login\n                +-- fstab       # we auto-mount the Plan 9 Filer filesystem to /mnt\n    +-- configs/\n        +-- v86_defconfig       # our custom buildroot config (make menuconfig)\n    +-- Config.in               # empty, but required https://buildroot.org/downloads/manual/manual.html#outside-br-custom\n    +-- external.mk             # empty, but required https://buildroot.org/downloads/manual/manual.html#outside-br-custom\n    +-- external.desc           # our v86 board config for make\n    +-- build-v86.sh            # entrypoint for Docker to run our build\n```\n\nIf you need or want to update these config files, do the following:\n\n```bash\n$ make BR2_EXTERNAL=/buildroot-v86 v86_defconfig\n$ make menuconfig\n...\n$ make savedefconfig\n$ make linux-menuconfig\n...\n$ make linux-savedefconfig\n```\n\n## Configuration Notes\n\nThese are the options I set when configuring buildroot for v86.  I'm only\nspecifying the things I set.\n\n```bash\n$ cd buildroot-2018.02\n$ make menuconfig\n```\n\nThen follow these config steps in the buildroot config menu (NOTE: these docs\nmay have drifted from the actual config in the source, so consult that first):\n\n### Target options\n\n* Target Architecture: i386\n* Target Architecture Variant: pentium mobile (Pentium with MMX, SSE)\n\n### Build options\n\n* Enable compiler cache (not strictly necessary, but helps with rebuilds)\n\n### Toolchain\n\n* C library: uLibc-ng (I'd like to experiment with musl too)\n\n### System configuration\n\n* remount root filesystem read-write during boot (I think this is unnecessary)\n* Root filesystem overlay directories: /build/overlay-fs (for etc/inittab)\n\n### Kernel\n\n* Linux Kernel: true\n* Defconfig name: i386\n* Kernel binary format: bzImage (vmlinux seemed to break on boot)\n\n### Target packages\n\nNeed to figure this out.  I tried adding imagemagik, git, uemacs, but they\nare all adding too much size to the image.\n\n### Filesystem images\n\n* cpio the root filesystem (for use as an initial RAM filesystem)\n* initial RAM filesystem linked into the linux kernel (not sure I need this, trying without...)\n* iso image\n    * Use initrd\n* tar the root filesystem Compression method (no compression)\n\n### Bootloaders\n\n* syslinux\n    * install isolinux\n\n## Linux configuration\n\nNow configure the Linux Kernel:\n\n```\n$ make linux-menuconfig\n```\n\nAnd set the following options to accomplish this:\n\n```\nCONFIG_NET_9P=y\nCONFIG_NET_9P_VIRTIO=y\nCONFIG_9P_FS=y\nCONFIG_9P_FS_POSIX_ACL=y\nCONFIG_PCI=y\nCONFIG_VIRTIO_PCI=y\nCONFIG_PCI=y\nCONFIG_VIRTIO_PCI=y\n```\n\n# Processor type and features\n\n* Processor family (Pentium-Pro) also tried Pentium M before. \n\n# Bus options (PCI, etc.)\n\n* PCI Debugging: true (I want to see what's happening with PCI errors, normally not needed)\n\n# Networking support\n\n* Plan 9 Resource Sharing Support (9P2000) (built into kernel * vs. M)\n    * 9P Virtio Transport (* - make this is on, it won't exist if virtio is off)\n    * Debug information (* - optional)\n\n# Device Drivers\n\n* Virtio drivers\n    * PCI driver for virtio devices (built into kernel * vs. M)\n        * Support for legacy virtio draft 0.9.X and older devices (New)\n    * Platform bus driver for memory mapped virtio devices (* vs. M) - not sure I need this...\n        * Memory mapped virtio devices parameter parsing - or this...\n\n# Filesystems\n\n* Caches\n    * General filesystem local caching manager (*)\n        * Filesystem caching on files (*)\n\n* Network File Systems\n    * Plan 9 Resource Sharing Support (9P2000) (*)\n        * Enable 9P client caching support\n        * 9P Posic Access Control Lists\n\nNow run `make`\n\nWhen it finishes, the built image is in `./output/images`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumphd%2Fbrowser-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumphd%2Fbrowser-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumphd%2Fbrowser-vm/lists"}