{"id":50152900,"url":"https://github.com/client-api/256-byte-vm","last_synced_at":"2026-05-24T09:02:14.705Z","repository":{"id":359935672,"uuid":"1248066752","full_name":"client-api/256-byte-vm","owner":"client-api","description":"A bootable x86 VM whose program is a single 256-byte file (boot.bin).","archived":false,"fork":false,"pushed_at":"2026-05-24T07:18:17.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T08:24:19.574Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/client-api.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T06:25:26.000Z","updated_at":"2026-05-24T07:17:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/client-api/256-byte-vm","commit_stats":null,"previous_names":["client-api/256-byte-vm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/client-api/256-byte-vm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2F256-byte-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2F256-byte-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2F256-byte-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2F256-byte-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/client-api","download_url":"https://codeload.github.com/client-api/256-byte-vm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/client-api%2F256-byte-vm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33427584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-05-24T09:02:11.867Z","updated_at":"2026-05-24T09:02:14.699Z","avatar_url":"https://github.com/client-api.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 256-byte-vm\n\nA bootable x86 VM whose program is a single **256-byte** file (`boot.bin`).\nThe build step wraps it into raw, qcow2, vdi, vmdk, vhd and iso images\nthat boot on QEMU, Proxmox, VMware, VirtualBox, Hyper-V, and any BIOS PC.\n\nBanner `ClientAPI` prints to BIOS video and COM1 serial. A serial REPL\nechoes each typed line back **reversed** (`hello` → `olleh`). The guest\nreacts to the hypervisor's ACPI power-button event — i.e. `qm shutdown`\non Proxmox — by writing `SLP_EN` to `PM1a_CNT` so the VM exits cleanly\nto S5 instead of being force-killed after the shutdown timeout.\n\n## Output formats\n\n`make all` produces every common VM disk format from `boot.bin`:\n\n| File                           | Format                | Use case                    |\n|--------------------------------|-----------------------|-----------------------------|\n| `boot.bin`                     | raw program           | dd / hexdump / `xxd`        |\n| `boot.iso`                     | ISO 9660 + El Torito  | bootable CD / `qemu -cdrom` |\n| `boot.qcow2`                   | QCOW2                 | Proxmox, libvirt, KVM       |\n| `boot.vmdk` + `boot-flat.vmdk` | VMware monolithicFlat | VMware Workstation / ESXi   |\n| `boot.vhd`                     | Microsoft VHD         | Hyper-V, Azure              |\n| `boot.vdi`                     | VirtualBox VDI        | VirtualBox                  |\n| `boot.img`                     | raw bootable disk     | `qemu -drive format=raw`    |\n\n## Build\n\n```bash\nsudo apt-get install -y nasm qemu-utils xorriso\nmake all\n```\n\nOutputs land in `build/`.\n\n## Run locally\n\n```bash\nmake run          # boot raw disk in qemu, screen + serial multiplexed\nmake run-serial   # boot raw disk, serial-only\nmake run-iso      # boot ISO in qemu\nmake test         # banner + REPL + ACPI shutdown e2e\n```\n\nQuit qemu with `Ctrl-A X`.\n\n## Use on Proxmox\n\n### As a CD image\n\n```bash\n# Upload boot.iso to your ISO storage (e.g. local:iso) and attach.\nqm create 9999 --memory 64 --net0 virtio,bridge=vmbr0 \\\n  --ide2 local:iso/boot.iso,media=cdrom \\\n  --boot order=ide2\nqm start 9999\nqm terminal 9999    # serial console\n```\n\n### As a disk image\n\n```bash\nqm importdisk 9999 build/boot.qcow2 local-lvm\nqm set 9999 --scsi0 local-lvm:vm-9999-disk-0\nqm set 9999 --boot order=scsi0\nqm start 9999\nqm terminal 9999\nqm shutdown 9999    # ACPI power-button — guest reacts via SLP_EN\n```\n\n## Inspect\n\n```bash\nmake check        # validate boot.bin size + code+data fits\nmake size         # one-line size report\n```\n\n```text\n$ make size\n222 / 256 bytes (34 free)\n```\n\n## What fits in 256 bytes\n\n- COM1 init at 9600 8N1\n- BIOS teletype output (`int 0x10` AH=0Eh)\n- Serial RX poll, line buffer (80 chars), in-place reverse, echo back\n- ACPI PM1a_EN write to arm the power-button event source\n- ACPI PM1a_STS polling for the hypervisor shutdown request\n- ACPI S5 shutdown via SLP_EN write to PM1a_CNT\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclient-api%2F256-byte-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclient-api%2F256-byte-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclient-api%2F256-byte-vm/lists"}