{"id":20826637,"url":"https://github.com/includeos/vmrunner","last_synced_at":"2025-05-07T20:38:36.117Z","repository":{"id":82454787,"uuid":"173761735","full_name":"includeos/vmrunner","owner":"includeos","description":"Utility for booting IncludeOS binaries","archived":false,"fork":false,"pushed_at":"2024-09-18T06:07:36.000Z","size":1019,"stargazers_count":4,"open_issues_count":4,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-07T20:38:28.400Z","etag":null,"topics":["conan"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/includeos.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-03-04T14:37:21.000Z","updated_at":"2024-09-18T06:07:41.000Z","dependencies_parsed_at":"2024-09-18T08:22:42.163Z","dependency_job_id":null,"html_url":"https://github.com/includeos/vmrunner","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/includeos%2Fvmrunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2Fvmrunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2Fvmrunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/includeos%2Fvmrunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/includeos","download_url":"https://codeload.github.com/includeos/vmrunner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954125,"owners_count":21830892,"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":["conan"],"created_at":"2024-11-17T23:09:39.281Z","updated_at":"2025-05-07T20:38:36.095Z","avatar_url":"https://github.com/includeos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vmrunner\nUtilities for booting [IncludeOS](https://github.com/includeos/includeos) binaries - _for testing and development only_.\n\n- `vmrunner.py` - a convenience wrapper around qemu, used by IncludeOS integration tests\n- `boot`        - a command line tool using vmrunner.py, that boots IncludeOS binaries with qemu\n- `grubify.sh`  - a script to create a bootable grub image from an IncludeOS binary\n\n\nBy default, the `boot` tool requires the `INCLUDEOS_CHAINLOADER` environment to\nbe defined, and pointing to a directory containing an IncludeOS chainloader.\n\n\n## Installing with nix\nThe supported way of using vmrunner is via nix. For example, in your nix shell, you can add:\n\n```nix\nvmrunner = pkgs.callPackage (builtins.fetchGit {\n  url = \"https://github.com/includeos/vmrunner\";\n}) {};\n```\nAfter which `vmrunner` can be added as a package:\n```\npackages = [\n  vmrunner\n  ...\n]\n```\n\nAn example shell.nix is provided here as well, which can be used as follows:\n\n```\n$ nix-shell\n\nExecuting pythonImportsCheckPhase\n\n================= vmrunner example shell =================\nThe vmrunner for IncludeOS tests requires bridged networking for full functionality.\nIn order to use bridge networking, you need the following:\n1. the qemu-bridge-helper needs sudo. Can be enabled with:\n   sudo chmod u+s /nix/store/ij3945kiq3p26vilqlc3ck5gvmrjsa2c-qemu-8.2.4/libexec/qemu-bridge-helper\n2. bridge43 must exist. Can be set up with $create_bridge :\n   /nix/store/9qhp9w3fkb7dh6q4647v889fmfaya7hs-create_bridge.sh\n3. /etc/qemu/bridge.conf must contain this line:\n   allow bridge43\nThese steps require sudo. Without them we're restricted to usermode networking.\n\n```\n\nNote the generated instructions for enabling bridged networking. Once the bridge is avalable, any of\nthe IncludeOS examples and integration tests should be able to boot:\n\n```\n$ export INCLUDEOS_CHAINLOADER=$(nix-build \u003cpath-to-IncludeOS\u003e/chainloader.nix)/bin/\n$ boot ./your/includeos/unikernel.elf.bin\n```\n\n## Installing and running with pipx\nInstalling and running with pipx should work as recommended here: https://packaging.python.org/en/latest/guides/creating-command-line-tools/#installing-the-package-with-pipx .\n\n```\npipx install .\n```\n\nWill by default install boot locally to your `$HOME/.local/bin`. It can also be run directly from `pipx` without installation.\n\n**Example:**\n\n```\n$ cd ~/IncludeOS\n$ export INCLUDEOS_CHAINLOADER=$(nix-build chainloader.nix)/bin\n$ pipx run --spec ~/vmrunner/ boot $(nix-build example.nix)/bin/hello_includeos.elf.bin\nLooking for chainloader:\nFound /nix/store/524d584z9apnbrnl5i6gzza9wsijj846-chainloader-static-i686-unknown-linux-musl-dev/bin/chainloader Type:  /nix/store/524d584z9apnbrnl5i6gzza9wsijj846-chainloader-static-i686-unknown-linux-musl-dev/bin/chainloader: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), statically linked, not stripped\n\nSeaBIOS (version 1.16.3-debian-1.16.3-2)\nBooting from ROM..* Multiboot begin: 0x9500\n* Multiboot cmdline @ 0x234092: /nix/store/524d584z9apnbrnl5i6gzza9wsijj846-chainloader-static-i686-unknown-linux-musl-dev/bin/chainloader \"\"\n* Multiboot end: 0x234100\n* Module list @ 0x234000\n...\n================================================================================\n\n                           #include\u003cos\u003e // Literally\n\n================================================================================\n     [ Kernel ] Stack: 0x1ffbe8\n     [ Kernel ] Boot magic: 0x2badb002, addr: 0x9500\n     [ x86_64 ] Initializing paging\n...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincludeos%2Fvmrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fincludeos%2Fvmrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincludeos%2Fvmrunner/lists"}