{"id":50396397,"url":"https://github.com/dudeperf3ct/ephemeral-playground","last_synced_at":"2026-05-30T21:01:42.682Z","repository":{"id":353549429,"uuid":"1215137962","full_name":"dudeperf3ct/ephemeral-playground","owner":"dudeperf3ct","description":"Creating ephemeral playgrounds using microVMs","archived":false,"fork":false,"pushed_at":"2026-04-24T10:35:29.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T12:29:34.915Z","etag":null,"topics":["firecracker","microvm"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/dudeperf3ct.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-04-19T14:31:15.000Z","updated_at":"2026-04-24T10:35:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dudeperf3ct/ephemeral-playground","commit_stats":null,"previous_names":["dudeperf3ct/ephemeral-playground"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dudeperf3ct/ephemeral-playground","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudeperf3ct%2Fephemeral-playground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudeperf3ct%2Fephemeral-playground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudeperf3ct%2Fephemeral-playground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudeperf3ct%2Fephemeral-playground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dudeperf3ct","download_url":"https://codeload.github.com/dudeperf3ct/ephemeral-playground/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudeperf3ct%2Fephemeral-playground/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33709269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"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":["firecracker","microvm"],"created_at":"2026-05-30T21:01:41.805Z","updated_at":"2026-05-30T21:01:42.671Z","avatar_url":"https://github.com/dudeperf3ct.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ephemeral playground\n\nFirecracker microVM playground driven by `just` tasks with script-backed implementation.\n\nUse `just help` for guided detached and interactive console flows.\n\n\u003e [!NOTE]\n\u003e Write up: https://dudeperf3ct.github.io/projects/ephermal_playground/\n\n## Prerequisites\n\n- Linux host with KVM (`/dev/kvm` present and accessible)\n- `bash`, `curl`, `tar`\n- `ip` (`iproute2`) and `iptables`/`iptables-nft`\n- `sudo` access (or run as root) for TAP/NAT setup\n- `just` (optional but recommended)\n- Local artifacts:\n  - `firecracker`: Firecracker binary\n  - `artifacts/vmlinux.bin`: Guest kernel image\n  - `artifacts/rootfs.ext4`: Guest root filesystem\n\nTo download Guest kernel and rootfs artifacts, refer [here](https://dudeperf3ct.github.io/projects/ephermal_playground/#configure-bootsource) and [here](https://dudeperf3ct.github.io/projects/ephermal_playground/#configure-rootfs).\n\n## Install/Update Firecracker Binary\n\nThis installs `firecracker` binary into the project root.\n\n```bash\njust firecracker-install\n# or pin a version\njust firecracker-install v1.15.1\n```\n\n## Interactive VM Shell (serial console)\n\nDetached mode (`just vm-up`) writes guest console output to `artifacts/firecracker.log`.\nFor an interactive shell, use foreground console mode with two terminals:\n\nTerminal A:\n\n```bash\njust start-firecracker-console\n```\n\nTerminal B:\n\n```bash\njust boot-vm\n```\n\nThen return to Terminal A and interact at the guest prompt.\n\nStop and clean up:\n\n```bash\njust stop-firecracker\n```\n\nRemove log files, socket file or any temporary files created:\n\n```bash\njust clean\n```\n\n## Individual steps\n\n```bash\njust check-kvm\njust check-artifacts\njust start-firecracker\njust network-up\njust configure-vm\njust start-instance\njust status\n```\n\nOr run everything in one shot:\n\n```bash\njust vm-up\n```\n\nThis start microVM in a detached state without any access to the guest OS console.\n\n`vm-up` also includes host networking (`network-up`) and guest IPv4 config via kernel boot args.\n\nStop and clean up:\n\n```bash\njust stop-firecracker\n```\n\nRemove log files, socket file or any temporary files created:\n\n```bash\njust clean\n```\n\n`just clean` stops Firecracker (if running) and removes API socket, pid/log files, metrics files, snapshot artifacts, and `/tmp/firecracker-v*` install temp files.\n\n## Snapshots\n\nCreate a snapshot from a running VM (pauses VM, saves state+memory, resumes VM):\n\n```bash\njust snapshot-create latest Full\n```\n\nThis writes files to `artifacts/snapshots/`:\n- `latest.vmstate`\n- `latest.mem`\n- `latest.meta`\n\nRestore snapshot into a fresh Firecracker process:\n\n```bash\njust snapshot-restore latest true\n```\n\nIf you restore with `false`, the VM stays paused:\n\n```bash\njust snapshot-restore latest false\njust vm-resume\n```\n\n\u003e [!NOTE]\n\u003e We implement only full snapshots in this project, but Firecracker also supports \"diff\" snapshots that save only the delta from a base snapshot.\n\n## Logs\n\nFollow guest serial output in detached mode:\n\n```bash\ntail -f artifacts/firecracker.log\n```\n\n## Expected Output\n\n- `just check-kvm`: shows `/dev/kvm` permissions and `OK` for user access.\n- `just check-artifacts`: lists `firecracker`, `vmlinux.bin`, `rootfs.ext4`, then `Artifacts look good.`\n- `just start-firecracker`: prints PID, socket path (`/tmp/firecracker.socket`), and log path.\n- `just configure-vm`: prints machine/boot/rootfs configuration steps and `VM configuration applied.`\n- `just network-up`: creates TAP (`tap0`), enables host forwarding, and configures NAT.\n- `just start-instance`: prints `MicroVM started.`\n- `just status`: shows process/socket status and recent `artifacts/firecracker.log` lines.\n- `just clean`: removes host-side temp/log/metrics/snapshot artifacts and tears down host networking.\n- `just start-firecracker-console` + `just boot-vm`: gives an interactive serial shell in Terminal A.\n\n## Networking\n\nBy default the project sets up:\n- Host TAP: `tap0` at `172.16.0.1/30`\n- Guest IP: `172.16.0.2/30` (injected via `boot_args` as `ip=...`)\n- Guest DNS: `8.8.8.8`, `1.1.1.1` (injected via `boot_args`)\n- NAT/forwarding from guest traffic to the host default interface\n\nBring networking up/down explicitly:\n\n```bash\njust network-up\njust network-down\n```\n\nUseful overrides:\n- `TAP_DEV` (default `tap0`)\n- `TAP_IP` (default `172.16.0.1`)\n- `GUEST_IP` (default `172.16.0.2`)\n- `TAP_CIDR` (default `30`)\n- `GUEST_IFACE` (default `eth0`)\n- `GUEST_DNS_1` (default `8.8.8.8`)\n- `GUEST_DNS_2` (default `1.1.1.1`)\n- `HOST_IFACE` (auto-detected if unset)\n\nDisable DNS injection by setting both empty, e.g. `GUEST_DNS_1= GUEST_DNS_2= just vm-up`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudeperf3ct%2Fephemeral-playground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdudeperf3ct%2Fephemeral-playground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudeperf3ct%2Fephemeral-playground/lists"}