{"id":39738009,"url":"https://github.com/dnakov/kage","last_synced_at":"2026-01-19T12:00:27.355Z","repository":{"id":332501680,"uuid":"1133310730","full_name":"dnakov/kage","owner":"dnakov","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-14T05:38:02.000Z","size":31,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T09:21:37.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnakov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-01-13T07:08:35.000Z","updated_at":"2026-01-14T05:38:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dnakov/kage","commit_stats":null,"previous_names":["dnakov/kage"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dnakov/kage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnakov%2Fkage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnakov%2Fkage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnakov%2Fkage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnakov%2Fkage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnakov","download_url":"https://codeload.github.com/dnakov/kage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnakov%2Fkage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28567861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T08:53:44.001Z","status":"ssl_error","status_checked_at":"2026-01-19T08:52:40.245Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-01-18T11:09:55.314Z","updated_at":"2026-01-19T12:00:27.348Z","avatar_url":"https://github.com/dnakov.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kage\n\nLightweight VM sandbox using QEMU with HVF acceleration. Written in Zig.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                              Host (macOS)                                   │\n│                                                                             │\n│  ┌──────────────┐                                                           │\n│  │    vmctl     │  CLI tool                                                 │\n│  │    (Zig)     │  - Spawns QEMU with HVF                                   │\n│  └──────┬───────┘  - WebSocket client                                       │\n│         │                                                                   │\n│         │ spawns                                                            │\n│         ▼                                                                   │\n│  ┌──────────────┐         ┌─────────────────────────────────────────────┐   │\n│  │    QEMU      │ hostfwd │              Linux VM (Ubuntu ARM64)        │   │\n│  │   (HVF)      │◄───────►│                                             │   │\n│  └──────────────┘  :8080  │  ┌─────────────────────────────────────┐    │   │\n│                           │  │              vmd (Zig)              │    │   │\n│                           │  │  - WebSocket server on :8080        │    │   │\n│                           │  │  - Process spawning with PTY        │    │   │\n│                           │  │  - Session/user management          │    │   │\n│                           │  └──────────────┬──────────────────────┘    │   │\n│                           │                 │                           │   │\n│                           │                 │ wraps                     │   │\n│                           │                 ▼                           │   │\n│                           │  ┌─────────────────────────────────────┐    │   │\n│                           │  │       sandbox-helper (Zig)          │    │   │\n│                           │  │  - Linux namespaces                 │    │   │\n│                           │  │  - Seccomp filtering                │    │   │\n│                           │  │  - Network isolation                │    │   │\n│                           │  └─────────────────────────────────────┘    │   │\n│                           └─────────────────────────────────────────────┘   │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## Quick Start\n\n```bash\n# Build everything\nzig build\n\n# Build the VM image (requires Docker)\ncd image-builder \u0026\u0026 ./build.sh\n\n# Start VM (returns port number)\n./zig-out/bin/vmctl start ./image-builder/artifacts/rootfs.img\n# =\u003e 52383\n\n# Execute commands\n./zig-out/bin/vmctl exec 52383 -- echo \"Hello from VM\"\n./zig-out/bin/vmctl exec 52383 -- ls -la\n\n# Web terminal\n./zig-out/bin/vmctl web 52383\n# Open http://localhost:8000\n\n# Stop VM\n./zig-out/bin/vmctl stop 52383\n```\n\n## Commands\n\n### start\n\n```bash\nvmctl start \u003crootfs.img\u003e [options]\n```\n\nOptions:\n- `--kernel \u003cpath\u003e` - Kernel image (default: auto-detected from rootfs dir)\n- `--initrd \u003cpath\u003e` - Initrd image (default: auto-detected from rootfs dir)\n- `--share \u003chost-path\u003e \u003ctag\u003e` - Share host directory via virtio-9p\n\n### exec\n\n```bash\nvmctl exec \u003cport\u003e [--raw] -- \u003ccommand\u003e [args...]\n```\n\nOptions:\n- `--raw` - Bypass sandbox (run as root with network access)\n\nStdin is forwarded, stdout/stderr streamed back. Exit code preserved.\n\n### install\n\n```bash\nvmctl install \u003cport\u003e \u003cfile\u003e\n```\n\nCopies a binary to `/usr/local/bin` in the VM via virtio-9p share.\n\n### web\n\n```bash\nvmctl web \u003cport\u003e [http-port]\n```\n\nStarts a web server with an xterm.js terminal connected to the VM.\nDefault HTTP port is 8000. Supports PTY for full terminal emulation.\n\n### stop\n\n```bash\nvmctl stop \u003cport\u003e\n```\n\n## Protocol\n\nBinary WebSocket frames: `[type:u8][len:u32 LE][json payload]`\n\n### Requests (host → guest)\n\n| Type | Name | Payload |\n|------|------|---------|\n| 0x01 | spawn | `{id, command, args, cwd?, uid?, gid?, network?, pty?}` |\n| 0x02 | stdin | `{id, handle, data}` |\n| 0x03 | kill | `{handle, signal?}` |\n| 0x04 | resize | `{id, handle, rows, cols}` |\n| 0x05 | mount | `{tag, mount_point, read_only?}` |\n| 0x06 | unmount | `{mount_point}` |\n| 0x07 | session_create | `{uid, username?}` |\n| 0x08 | binary_install | `{name, data, executable?}` |\n\n### Responses (guest → host)\n\n| Type | Name | Payload |\n|------|------|---------|\n| 0x81 | spawned | `{id, pid, handle}` |\n| 0x82 | stdout | `{id, data}` |\n| 0x83 | stderr | `{id, data}` |\n| 0x84 | exit | `{id, code, signal?}` |\n| 0x85 | error | `{id, code, message}` |\n| 0x86 | ok | `{}` |\n\n## Project Structure\n\n```\nkage/\n├── src/\n│   ├── host/           # vmctl CLI, QEMU launcher, WebSocket client\n│   ├── guest/          # vmd daemon, WebSocket server, process management\n│   └── shared/         # Protocol definitions\n├── sandbox-helper/     # Namespace isolation with seccomp\n├── image-builder/      # Scripts to build Ubuntu rootfs\n└── build.zig\n```\n\n## Requirements\n\n- macOS 14+ with Apple Silicon (HVF)\n- QEMU (`brew install qemu`)\n- Zig 0.15+\n- Docker (for building VM images)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnakov%2Fkage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnakov%2Fkage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnakov%2Fkage/lists"}