{"id":43793693,"url":"https://github.com/cephalization/bonfire","last_synced_at":"2026-02-05T20:36:23.036Z","repository":{"id":335418429,"uuid":"1145224942","full_name":"cephalization/bonfire","owner":"cephalization","description":"A self-hosted platform for ephemeral Firecracker microVMs, optimized for remote code development and execution.","archived":false,"fork":false,"pushed_at":"2026-01-30T03:58:01.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-30T19:21:42.793Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/cephalization.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-29T15:20:33.000Z","updated_at":"2026-01-30T03:58:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cephalization/bonfire","commit_stats":null,"previous_names":["cephalization/bonfire"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cephalization/bonfire","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fbonfire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fbonfire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fbonfire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fbonfire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cephalization","download_url":"https://codeload.github.com/cephalization/bonfire/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fbonfire/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29133400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T19:36:52.185Z","status":"ssl_error","status_checked_at":"2026-02-05T19:35:40.941Z","response_time":65,"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-02-05T20:36:22.651Z","updated_at":"2026-02-05T20:36:23.013Z","avatar_url":"https://github.com/cephalization.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bonfire\n\n\u003e **Warning**: This is an experimental project intended for learning and exploration. It is not production-ready and may have security vulnerabilities, bugs, or breaking changes. Use at your own risk.\n\nA self-hosted platform for ephemeral Firecracker microVMs, optimized for remote code development and execution.\n\n## Features\n\n- **Web UI** - Manage VMs from your browser (mobile-responsive)\n- **Terminal Access** - Connect to VMs via ghostty-web terminal in the browser\n- **TypeScript SDK** - Programmatic control of your VMs\n- **CLI** - Full-featured command-line interface\n- **Ephemeral VMs** - Spin up and tear down VMs in seconds\n\n## Tech Stack\n\n- **Runtime**: Node.js 24+\n- **Backend**: Hono\n- **Frontend**: React + Vite + shadcn/ui\n- **Database**: SQLite + Drizzle\n- **Auth**: Better Auth\n- **Terminal**: ghostty-web\n- **CLI**: Clack\n- **VMs**: Firecracker microVMs\n\n## Quick Start (Docker - Recommended)\n\nGet from zero to a running VM in under 5 minutes with Docker and the CLI.\n\n### Prerequisites\n\n- Linux host with KVM support (`/dev/kvm` must exist)\n- Docker and Docker Compose\n\n### Installation\n\n1. **Clone and build the VM image**:\n\n```bash\ngit clone https://github.com/cephalization/bonfire.git\ncd bonfire\n./scripts/build-agent-image-docker.sh\n```\n\nThis creates the kernel and rootfs needed to run VMs:\n\n- `images/agent-kernel` (~10 MB)\n- `images/agent-rootfs.ext4` (~4 GB sparse file)\n\n2. **Start Bonfire** (auto-registers the image on startup):\n\n```bash\ndocker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up -d --remove-orphans\n```\n\n3. **Install the CLI**:\n\n```bash\nnpm install -g @bonfire/cli\n\n# Or use npx (no install)\nnpx @bonfire/cli\n```\n\n4. **Login** (uses default credentials):\n\n```bash\nbonfire login\n# API URL: http://localhost:3000\n# API Key: admin123\n```\n\n5. **Create and connect to your first VM**:\n\n```bash\n# Create, start, and connect\nbonfire vm create my-first-vm --image=local:agent-ready\nbonfire vm start my-first-vm\nbonfire vm ssh my-first-vm\n```\n\nThat's it! You're now connected to your Firecracker microVM via SSH.\n\n### Alternative: Using the Web UI\n\nIf you prefer a graphical interface:\n\n1. Open http://localhost:5173 in your browser\n2. Log in with default credentials:\n   - Email: `admin@example.com`\n   - Password: `admin123`\n3. Click \"New VM\", select `local:agent-ready` image\n4. Start the VM and click \"SSH\" to connect\n\n### Production Compose\n\nFor a production-like setup (static web served by nginx with `/api` reverse-proxied to the API):\n\n```bash\nBETTER_AUTH_SECRET=\"change-me\" \\\nBETTER_AUTH_URL=\"https://your-hostname\" \\\ndocker compose -f docker/docker-compose.yml -f docker/docker-compose.prod.yml up\n```\n\n- Web UI: http://localhost\n- API: http://localhost:3000\n\n### Alternative: Bare Metal Installation\n\n\u003e **Warning**: Running directly on bare metal modifies system networking configuration, installs system packages, and requires root access. This approach carries more risk and is only recommended for advanced users who understand the implications.\n\n**Prerequisites:**\n\n- Linux host with KVM support (`/dev/kvm` must exist)\n- Node.js 24+ (use corepack + pnpm)\n- Root access (for network/VM management)\n\n**Steps:**\n\n1. **Clone and setup**:\n\n```bash\ngit clone https://github.com/cephalization/bonfire.git\ncd bonfire\ncorepack enable \u0026\u0026 pnpm install\n```\n\n2. **System setup** (installs Firecracker, configures bridge/NAT):\n\n```bash\nsudo ./scripts/setup.sh\n```\n\n3. **Build the VM image**:\n\n```bash\n./scripts/build-agent-image-docker.sh\n```\n\n4. **Start servers** (in one terminal):\n\n```bash\npnpm run dev\n```\n\n5. **Register the image** (in another terminal, after API is ready):\n\n```bash\ncurl -X POST http://localhost:3000/api/images/local \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"reference\": \"local:agent-ready\",\n    \"kernelPath\": \"/var/lib/bonfire/images/agent-kernel\",\n    \"rootfsPath\": \"/var/lib/bonfire/images/agent-rootfs.ext4\"\n  }'\n```\n\n6. **Install CLI and login**:\n\n```bash\nnpm install -g @bonfire/cli\nbonfire login\n# API URL: http://localhost:3000\n# API Key: admin123 (from .env)\n```\n\n7. **Create and connect to your first VM**:\n\n```bash\nbonfire vm create my-first-vm --image=local:agent-ready\nbonfire vm start my-first-vm\nbonfire vm ssh my-first-vm\n```\n\nOr use the Web UI at http://localhost:5173\n\n## System Impact\n\nUnderstanding what Bonfire does to your system helps you make informed decisions about deployment and cleanup.\n\n### System Changes Overview\n\nWhen you run Bonfire (especially on bare metal), it makes several types of system modifications:\n\n#### Network Configuration\n\n**Bridge Interface**: Creates a Linux bridge (`bonfire0` by default) that persists until manually removed\n\n- Acts as the gateway for all VMs (10.0.100.1)\n- Visible in `ip link` and `bridge link` outputs\n- Provides the network backbone for VM communication\n\n**TAP Devices**: Creates virtual network interfaces for each running VM\n\n- Naming pattern: `tap-bf-{first-8-chars-of-vm-id}`\n- Automatically cleaned up when VMs stop\n- Requires elevated privileges (root or CAP_NET_ADMIN)\n\n**IP Tables Rules**: Adds NAT rules for internet access\n\n- One rule in `nat/POSTROUTING` chain for the VM subnet\n- Enables VMs to reach the internet through the host\n- Persists until removed or system reboots\n\n**IP Forwarding**: Enables kernel-level packet forwarding\n\n- Required for NAT to function\n- May create `/etc/sysctl.d/99-bonfire.conf` for persistence\n- Affects the entire system, not just Bonfire\n\n#### File System Modifications\n\n**Data Directories**: Creates the following persistent directories:\n\n| Directory                 | Purpose                          | Typical Size                 |\n| ------------------------- | -------------------------------- | ---------------------------- |\n| `/var/lib/bonfire`        | Main data directory              | ~10 MB (database + metadata) |\n| `/var/lib/bonfire/images` | Base VM images (kernel + rootfs) | ~4 GB per image              |\n| `/var/lib/bonfire/vms`    | Per-VM runtime files             | Up to 4 GB per VM            |\n| `/var/lib/bonfire/keys`   | SSH key storage                  | ~1 KB per VM                 |\n| `~/.bonfire` (CLI)        | User configuration               | ~1 KB                        |\n| `~/.bonfire/keys` (CLI)   | Downloaded SSH keys              | ~1 KB per VM                 |\n\n**Per-VM Files**: Each VM creates:\n\n- Writable rootfs copy (`{vmId}.rootfs.ext4`) - sparse file, up to 4 GB\n- Firecracker socket (`{vmId}.sock`)\n- Stderr log file (`{vmId}.firecracker.stderr.log`)\n- SSH key pair (`vm-{vmId}` and `vm-{vmId}.pub`)\n\n**Temporary Files**:\n\n- Mount points for SSH key injection (`/tmp/bonfire-mount-{vmId}`)\n- Temporary SSH key generation directories\n- Test databases (during development/testing)\n\n#### Process Management\n\n**External Processes Spawned**:\n\n- **Firecracker**: One process per running VM (the actual microVM)\n- **ip commands**: For TAP device and bridge management\n- **ssh-keygen**: For VM SSH key generation\n- **mount/umount**: For rootfs modification during SSH key injection\n- **cp**: For creating writable rootfs copies (with sparse file support)\n- **SSH client**: When using `bonfire vm ssh` command\n\n**Resource Requirements**:\n\n| Resource | Per VM                              | Host Requirements            |\n| -------- | ----------------------------------- | ---------------------------- |\n| Memory   | 128 MiB - 64 GiB (default: 512 MiB) | +~30 MB Firecracker overhead |\n| vCPUs    | 1-32 (default: 1)                   | Shared with host             |\n| Disk     | Up to 4 GB per VM                   | Plus base images             |\n| Network  | 1 IP from 10.0.100.0/24             | Bridge + TAP overhead        |\n\n**Maximum Capacity**: Up to 253 concurrent VMs (limited by IP pool size)\n\n#### Privilege Requirements\n\n**Required Capabilities**:\n\n- `CAP_NET_ADMIN` - Network interface management (TAP devices, bridges, iptables)\n- `CAP_SYS_ADMIN` - Mount operations, system administration\n- `/dev/kvm` access - Hardware virtualization\n\n**Root Access Needed For**:\n\n- Initial setup (bridge creation, iptables rules, sysctl changes)\n- TAP device creation and management\n- Mounting loop devices for rootfs modification\n- Installing Firecracker binary to `/usr/local/bin`\n\n### Cleanup Procedures\n\n#### Full System Cleanup (Bare Metal)\n\nIf you want to completely remove Bonfire's system changes:\n\n```bash\n# 1. Stop all VMs\npkill -f firecracker\n\n# 2. Remove all TAP devices\nfor tap in $(ip link show | grep -oE 'tap-bf-[a-z0-9]+' | sort -u); do\n    ip link delete \"$tap\" 2\u003e/dev/null || true\ndone\n\n# 3. Remove bridge\nip link delete bonfire0 2\u003e/dev/null || true\n\n# 4. Remove NAT rule\niptables -t nat -D POSTROUTING -s 10.0.100.0/24 ! -o bonfire0 -j MASQUERADE\n\n# 5. Disable IP forwarding\nsysctl -w net.ipv4.ip_forward=0\nrm -f /etc/sysctl.d/99-bonfire.conf\n\n# 6. Remove data directories (WARNING: destroys all VM data)\nrm -rf /var/lib/bonfire\nrm -rf ~/.bonfire\n\n# 7. Remove Firecracker binary\nrm -f /usr/local/bin/firecracker\n```\n\n#### Docker Cleanup\n\nMuch simpler - just remove the containers and volumes:\n\n```bash\n# Stop and remove containers\ndocker compose -f docker/docker-compose.yml down\n\n# Remove volumes (destroys all data)\ndocker volume rm bonfire_bonfire-data\n```\n\n### Bare Metal vs Docker: Impact Comparison\n\n| Aspect                 | Bare Metal                      | Docker                              |\n| ---------------------- | ------------------------------- | ----------------------------------- |\n| **Network Changes**    | Direct on host                  | Inside container namespace          |\n| **Cleanup**            | Manual steps required           | Simple container/volume removal     |\n| **Bridge Persistence** | Persists until manually removed | Removed with container              |\n| **IPT Persistence**    | Persists until manually removed | Removed with container              |\n| **Privileges**         | Root required                   | Can use capabilities                |\n| **Isolation**          | Minimal                         | Better process/filesystem isolation |\n| **Performance**        | Native                          | Minimal overhead                    |\n| **Complexity**         | Higher                          | Lower                               |\n\n### Recommendation\n\n**Use Docker for development workstations** where you want:\n\n- Easy cleanup and no persistent system changes\n- Protection against accidentally leaving bridges/TAP devices\n- Isolation from your main network stack\n- Simple \"reset\" capability\n\n**Use bare metal for dedicated VM hosts** where:\n\n- Performance is critical\n- You're already managing the infrastructure\n- You want VMs to persist across container restarts\n- You accept the manual cleanup responsibility\n\n## Development Setup\n\n### Monorepo Structure\n\n```\nbonfire/\n├── packages/\n│   ├── api/           # Hono API server\n│   ├── web/           # React + Vite frontend\n│   ├── sdk/           # TypeScript SDK (auto-generated)\n│   └── cli/           # CLI with Clack\n├── docker/            # Docker configurations\n├── scripts/           # Setup and utility scripts\n└── e2e/              # End-to-end tests\n```\n\n### Environment Variables\n\nFor Docker Compose, put environment variables in a repo-root `.env` file (Docker Compose reads it automatically).\n\nFor bare metal (running `packages/api` directly), you can also put them in `packages/api/.env`.\n\nReview and update the values as needed:\n\n```env\nDATABASE_URL=/var/lib/bonfire/bonfire.db\nBETTER_AUTH_SECRET=\u003cgenerate-a-secure-random-string\u003e\nBETTER_AUTH_URL=http://localhost:3000\nPORT=3000\nNODE_ENV=development\n\n# Initial admin user (required for first login)\nINITIAL_ADMIN_EMAIL=admin@example.com\nINITIAL_ADMIN_PASSWORD=\u003cchoose-a-strong-password\u003e\nINITIAL_ADMIN_NAME=Admin\n```\n\n#### Authentication Setup\n\nBonfire uses Better Auth for authentication with email/password. On first startup, if `INITIAL_ADMIN_EMAIL` and `INITIAL_ADMIN_PASSWORD` are configured, an admin user will be automatically created.\n\n### Agent Sessions (Bootstrap)\n\nAgent sessions currently rely on a guest bootstrap process to become `ready`.\n\n- Historical approach: SSH-based bootstrap.\n- Planned approach: serial-console bootstrap (no SSH). See `docs/AGENT_SERIAL_BOOTSTRAP.md`.\n\n\u003e **Security Note**: The default credentials (`admin@example.com` / `admin123`) are for local development only. Always change these values in your `.env` file before exposing the service to any network.\n\n- Users can have either `admin` or `member` role\n- Admin users have full permissions (all API endpoints)\n- Member users have limited access (can be restricted per-endpoint)\n- The initial admin user can create additional users through the API\n\n### Running Tests\n\n```bash\n# Unit tests (run anywhere)\npnpm -r test\n\n# Integration tests (requires Docker)\npnpm run test:int\n\n# E2E tests (requires KVM, Linux only)\npnpm run test:e2e\n\n# All tests\npnpm run test:all\n```\n\n### Building\n\n```bash\n# Build all packages\npnpm run build\n\n# Build specific package\npnpm run build -- --filter=@bonfire/api\n```\n\n## Architecture Overview\n\n### System Architecture\n\n```\n┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐\n│   Web Browser   │────▶│   Web UI (Vite) │────▶│  API (Hono)     │\n└─────────────────┘     └─────────────────┘     └────────┬────────┘\n                                                         │\n                              ┌──────────────────────────┼──────────────────────────┐\n                              │                          │                          │\n                              ▼                          ▼                          ▼\n                    ┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐\n                    │  Firecracker    │        │  Network (TAP)  │        │   SQLite DB     │\n                    │   microVMs      │        │   + Bridge      │        │   (Drizzle)     │\n                    └─────────────────┘        └─────────────────┘        └─────────────────┘\n```\n\n### Key Components\n\n1. **API Server** (`packages/api`)\n   - Hono web framework with OpenAPI spec\n   - RESTful endpoints for VM lifecycle\n   - WebSocket proxy for terminal access\n   - Better Auth integration\n\n2. **Web UI** (`packages/web`)\n   - React with TypeScript\n   - Tailwind CSS + shadcn/ui components\n   - ghostty-web for terminal emulation\n   - Mobile-responsive design\n\n3. **SDK** (`packages/sdk`)\n   - Auto-generated from OpenAPI spec\n   - TypeScript client with full type safety\n\n4. **CLI** (`packages/cli`)\n   - Clack for interactive prompts\n   - Commands: vm, image, config, login\n\n### VM Lifecycle\n\n1. **Create** - VM record created in DB with `creating` status\n2. **Start** - Network resources allocated, Firecracker process spawned with serial console pipes\n3. **Running** - VM boots, serial console available via WebSocket terminal\n4. **Stop** - Firecracker process stopped, network resources and pipes released\n5. **Delete** - VM record removed from DB\n\n### Network Architecture\n\n- Bridge: `bonfire0` (10.0.100.1/24)\n- Each VM gets:\n  - TAP device attached to bridge\n  - Unique MAC address\n  - IP from pool (10.0.100.2 - 10.0.100.254)\n- NAT for internet access via host\n\n## Default Configuration\n\n| Setting          | Default Value                         |\n| ---------------- | ------------------------------------- |\n| VM vCPUs         | 1                                     |\n| VM Memory        | 512 MiB                               |\n| Bridge Name      | `bonfire0`                            |\n| Bridge Subnet    | `10.0.100.0/24`                       |\n| Gateway IP       | `10.0.100.1`                          |\n| VM IP Range      | `10.0.100.2` - `10.0.100.254`         |\n| Images Directory | `/var/lib/bonfire/images/`            |\n| VMs Directory    | `/var/lib/bonfire/vms/`               |\n| Database Path    | `/var/lib/bonfire/bonfire.db`         |\n| API Port         | `3000`                                |\n| Default Image    | `firecracker-quickstart:ubuntu-24.04` |\n\n## Documentation\n\n- [PLAN.md](./PLAN.md) - Full implementation plan and technical details\n- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines\n\n## Status\n\nThis is an experimental learning project under active development. Expect breaking changes, incomplete features, and potential security issues. See [PLAN.md](./PLAN.md) for implementation status.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcephalization%2Fbonfire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcephalization%2Fbonfire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcephalization%2Fbonfire/lists"}