{"id":32718425,"url":"https://github.com/tsirysndr/openbsd-up","last_synced_at":"2026-04-16T04:02:14.621Z","repository":{"id":321932472,"uuid":"1087576840","full_name":"tsirysndr/openbsd-up","owner":"tsirysndr","description":"A simple CLI tool to spin up OpenBSD virtual machines using QEMU with minimal fuss.","archived":false,"fork":false,"pushed_at":"2025-11-16T15:12:36.000Z","size":251,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T01:28:35.489Z","etag":null,"topics":["bsd","deno","openbsd","qemu","qemu-kvm","typescript","virtualization"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsirysndr.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":"2025-11-01T07:35:11.000Z","updated_at":"2025-11-16T15:07:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tsirysndr/openbsd-up","commit_stats":null,"previous_names":["tsirysndr/openbsd-up"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/tsirysndr/openbsd-up","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fopenbsd-up","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fopenbsd-up/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fopenbsd-up/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fopenbsd-up/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsirysndr","download_url":"https://codeload.github.com/tsirysndr/openbsd-up/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fopenbsd-up/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"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":["bsd","deno","openbsd","qemu","qemu-kvm","typescript","virtualization"],"created_at":"2025-11-02T18:00:23.818Z","updated_at":"2026-04-16T04:02:14.613Z","avatar_url":"https://github.com/tsirysndr.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 🐡 openbsd-up\n\n[![release](https://github.com/tsirysndr/openbsd-up/actions/workflows/release.yml/badge.svg)](https://github.com/tsirysndr/openbsd-up/actions/workflows/release.yml)\n[![JSR](https://jsr.io/badges/@tsiry/openbsd-up)](https://jsr.io/@tsiry/openbsd-up)\n[![deno module](https://shield.deno.dev/x/openbsdup)](https://deno.land/x/openbsdup)\n![deno compatibility](https://shield.deno.dev/deno/^2.5.6)\n\nA comprehensive CLI tool to manage OpenBSD virtual machines using QEMU with\nminimal fuss. Create, start, stop, and manage multiple OpenBSD VMs with\npersistent state tracking.\n\n![Preview](./preview.png)\n\n## ✨ Features\n\n- 🚀 **Quick Start**: Launch OpenBSD VMs with a single command\n- 📦 **Auto-Download**: Automatically fetches OpenBSD ISO images from official\n  CDN or OCI registries\n- 🔢 **Version Support**: Specify any OpenBSD version (e.g., `7.8`, `6.4`)\n- 💾 **Flexible Storage**: Support for persistent disk images in multiple\n  formats with auto-creation\n- 🐳 **OCI Support**: Push, pull, and manage OpenBSD VM images using OCI\n  registries\n- ⚙️ **Configurable**: Customize CPU, memory, cores, and more via TOML config\n  file\n- 🌐 **Network Ready**: Support for both NAT (SSH port forwarding) and bridge\n  networking\n- 🔌 **Port Forwarding**: Custom port mapping with `--port-forward` option\n- 📝 **Serial Console**: Direct terminal access via `-nographic` mode\n- 🗃️ **VM Management**: Persistent state tracking with SQLite database\n- 📋 **VM Lifecycle**: Start, stop, restart, list, and inspect VMs with unique\n  names\n- 🗑️ **VM Cleanup**: Remove VMs and images with `rm` and `rmi` commands\n- 📊 **Logs Management**: View and follow VM logs in real-time\n- 🔄 **Background Mode**: Run VMs detached with `--detach` option\n- 🎯 **Smart Detection**: Automatically detects existing disk images to avoid\n  data loss\n- 🔗 **Bridge Support**: Automatic bridge network creation and QEMU\n  configuration\n- 🏷️ **Image Tags**: Tag and manage VM images with custom names\n- 💽 **Volume Management**: Create, attach, list, and manage persistent volumes\n- 🌐 **HTTP API**: RESTful API server for programmatic VM management\n\n## 🛠️ Requirements\n\n- [Deno](https://deno.com) runtime\n- QEMU with KVM support (`qemu-system-x86_64`)\n- `curl` for downloading ISOs\n- `sudo` access (for bridge networking only)\n\n## 📥 Installation\n\n```bash\ndeno install -A -g -r -f jsr:@tsiry/openbsd-up\n```\n\n## 🎯 Usage\n\n### Basic Examples\n\n```bash\n# Launch latest default version (7.8) - creates a new VM with random name\nopenbsd-up\n\n# Launch specific OpenBSD version\nopenbsd-up 7.6\n\n# Use local ISO file\nopenbsd-up /path/to/openbsd.iso\n\n# Download from custom URL\nopenbsd-up https://cdn.openbsd.org/pub/OpenBSD/7.8/amd64/install78.iso\n```\n\n### VM Management\n\n```bash\n# List running VMs\nopenbsd-up ps\n\n# List all VMs (including stopped)\nopenbsd-up ps --all\n\n# Start a specific VM by name or ID\nopenbsd-up start my-vm-name\n\n# Start a VM in the background (detached mode)\nopenbsd-up start my-vm-name --detach\n\n# Stop a running VM\nopenbsd-up stop my-vm-name\n\n# Restart a VM\nopenbsd-up restart my-vm-name\n\n# Remove a VM from state tracking\nopenbsd-up rm my-vm-name\n\n# Inspect VM details and configuration\nopenbsd-up inspect my-vm-name\n\n# View VM logs\nopenbsd-up logs my-vm-name\n\n# Follow VM logs in real-time\nopenbsd-up logs my-vm-name --follow\n```\n\n### Image Management\n\n```bash\n# Pull an OpenBSD image from an OCI registry\nopenbsd-up pull ghcr.io/tsirysndr/openbsd:7.8\n\n# Push an OpenBSD image to an OCI registry\nopenbsd-up push my-openbsd-image:latest\n\n# Tag a VM\nopenbsd-up tag vm-name ghcr.io/tsirysndr/openbsd:7.8\n\n# List local images\nopenbsd-up images\n\n# Remove an image\nopenbsd-up rmi my-openbsd:latest\n\n# Run a VM from an image\nopenbsd-up run ghcr.io/tsirysndr/openbsd:7.8\n\n# Inspect image details\nopenbsd-up inspect ghcr.io/tsirysndr/openbsd:7.8\n```\n\n### Volume Management\n\n```bash\n# List all volumes\nopenbsd-up volumes\n\n# Attach a volume to a VM (creates volume if it doesn't exist)\nopenbsd-up start my-vm --volume data-volume\n\n# Inspect volume details\nopenbsd-up volume inspect data-volume\n\n# Remove a volume\nopenbsd-up volume rm data-volume\n```\n\n### Configuration File\n\n```bash\n# Initialize a vmconfig.toml configuration file\nopenbsd-up init\n\n# Start VM using configuration from vmconfig.toml\nopenbsd-up\n```\n\n### Advanced Configuration\n\n```bash\n# Custom VM with persistent disk (auto-created if needed)\nopenbsd-up 7.8 \\\n  --cpus 4 \\\n  --memory 4G \\\n  --cpu host \\\n  --image disk.img \\\n  --disk-format qcow2 \\\n  --size 40G\n\n# Run VM in background (detached mode)\nopenbsd-up 7.8 --detach\n\n# Bridge networking (requires sudo)\nopenbsd-up 7.8 --bridge br0\n\n# Custom port forwarding (host:guest port mappings)\nopenbsd-up 7.8 --port-forward 8080:80,3000:3000\n\n# Save downloaded ISO to specific location\nopenbsd-up 7.8 --output ~/isos/openbsd-78.iso\n```\n\n## 🎛️ Command Line Options\n\n### Global Options\n\n| Option           | Short | Description                                                  | Default        |\n| ---------------- | ----- | ------------------------------------------------------------ | -------------- |\n| `--output`       | `-o`  | Output path for downloaded ISO                               | Auto-generated |\n| `--cpu`          | `-c`  | CPU type to emulate                                          | `host`         |\n| `--cpus`         | `-C`  | Number of CPU cores                                          | `2`            |\n| `--memory`       | `-m`  | RAM allocation                                               | `2G`           |\n| `--image`        | `-i`  | Path to persistent disk image                                | None           |\n| `--disk-format`  |       | Disk format (qcow2, raw, etc.)                               | `raw`          |\n| `--size`         |       | Size of disk image to create if it doesn't exist             | `20G`          |\n| `--bridge`       | `-b`  | Name of the network bridge to use for networking (e.g., br0) | None           |\n| `--detach`       | `-d`  | Run VM in the background and print VM name                   | `false`        |\n| `--port-forward` | `-p`  | Port forwarding rules (hostPort:guestPort, comma-separated)  | None           |\n\n### Subcommands\n\n| Command              | Description                            | Example                                    |\n| -------------------- | -------------------------------------- | ------------------------------------------ |\n| `ps`                 | List virtual machines                  | `openbsd-up ps --all`                      |\n| `start \u003cn\u003e`          | Start a stopped VM by name or ID       | `openbsd-up start my-vm`                   |\n| `stop \u003cn\u003e`           | Stop a running VM by name or ID        | `openbsd-up stop my-vm`                    |\n| `restart \u003cn\u003e`        | Restart a VM by name or ID             | `openbsd-up restart my-vm`                 |\n| `rm \u003cn\u003e`             | Remove a VM from state tracking        | `openbsd-up rm my-vm`                      |\n| `inspect \u003cn\u003e`        | Show detailed VM/image information     | `openbsd-up inspect my-vm`                 |\n| `logs \u003cn\u003e`           | View VM logs                           | `openbsd-up logs my-vm`                    |\n| `init`               | Initialize a vmconfig.toml config file | `openbsd-up init`                          |\n| `pull \u003cimage\u003e`       | Pull an OpenBSD VM image from registry | `openbsd-up pull ghcr.io/user/openbsd:7.8` |\n| `push \u003cimage\u003e`       | Push an OpenBSD VM image to registry   | `openbsd-up push my-openbsd:latest`        |\n| `tag \u003cs\u003e \u003ct\u003e`        | Tag an image with a new name           | `openbsd-up tag source:tag target:tag`     |\n| `images`             | List local images                      | `openbsd-up images`                        |\n| `rmi \u003cimage\u003e`        | Remove an image                        | `openbsd-up rmi my-openbsd:latest`         |\n| `run \u003cimage\u003e`        | Run a VM from an image                 | `openbsd-up run ghcr.io/user/openbsd:7.8`  |\n| `volumes`            | List all volumes                       | `openbsd-up volumes`                       |\n| `volume inspect \u003cn\u003e` | Inspect volume details                 | `openbsd-up volume inspect data-volume`    |\n| `volume rm \u003cn\u003e`      | Remove a volume                        | `openbsd-up volume rm data-volume`         |\n| `serve`              | Start HTTP API server                  | `openbsd-up serve --port 8891`             |\n\n## 🖥️ Console Setup\n\nWhen OpenBSD boots, you'll see the boot loader prompt, enter the following\ncommand:\n\n```sh\nset tty com0\nboot\n```\n\n## 🔌 Networking\n\nThe tool supports two networking modes:\n\n### NAT Mode (Default)\n\n- **SSH Port Forward**: `localhost:2222` → VM port `22` (default)\n- **Custom Port Forwarding**: Configure with `--port-forward` option\n- **Network Device**: Intel E1000 emulated NIC\n- No special privileges required\n\n#### Custom Port Forwarding Examples\n\n```bash\n# Forward host port 8080 to VM port 80\nopenbsd-up 7.8 --port-forward 8080:80\n\n# Multiple port forwards\nopenbsd-up 7.8 --port-forward 8080:80,3000:3000,2222:22\n\n# Access services after VM is running\ncurl http://localhost:8080  # Access VM's port 80\nssh -p 2222 user@localhost  # SSH to VM\n```\n\n### Bridge Mode\n\n- **Direct Bridge Access**: VM gets IP from bridge network\n- **Network Device**: Intel E1000 emulated NIC with custom MAC\n- Requires `sudo` privileges for QEMU bridge access\n- Automatically creates bridge network if it doesn't exist\n- Sets up QEMU bridge configuration in `/etc/qemu/bridge.conf`\n\nConnect via SSH after installation:\n\n```bash\n# NAT mode\nssh -p 2222 user@localhost\n\n# Bridge mode (use VM's actual IP)\nssh user@\u003cvm-ip-address\u003e\n```\n\n## �️ VM State Management\n\n`openbsd-up` automatically tracks VM state using a SQLite database stored in\n`~/.openbsd-up/state.sqlite`. Each VM gets:\n\n- **Unique ID**: Auto-generated CUID for reliable identification\n- **Random Name**: Human-readable names (e.g., `ancient-butterfly`) for easy\n  reference\n- **Persistent Config**: CPU, memory, disk, and network settings preserved\n- **Status Tracking**: RUNNING/STOPPED status with process ID tracking\n- **MAC Address**: Consistent network identity across restarts\n\nThe state database allows you to:\n\n- Resume VMs exactly as configured\n- List all VMs with their current status\n- Start/stop VMs by name or ID\n- Inspect detailed VM configurations\n\n## 💡 Tips\n\n- 🐏 Allocate at least 2GB RAM for smooth installation\n- 💿 ISOs are cached - re-running with same version skips download\n- 📀 Disk images are auto-created if `--image` path doesn't exist\n- 🔒 Tool detects non-empty disk images and skips ISO mounting to prevent data\n  loss\n- 🏷️ Use VM names for easy management: `openbsd-up start my-web-server`\n- 🌉 Bridge networking requires sudo but provides direct network access\n- 📊 Use `openbsd-up ps --all` to see both running and stopped VMs\n- 🔄 Use `--detach` mode to run VMs in the background\n- 🔗 Configure custom port forwarding with `--port-forward host:guest`\n- 📝 Monitor VM activity with `openbsd-up logs \u003cname\u003e --follow`\n- 🗑️ Clean up unused VMs with `openbsd-up rm \u003cname\u003e`\n- 💽 Use volumes for shared persistent storage across VMs\n- ⚙️ Use `vmconfig.toml` configuration file for consistent VM setups\n- 🌐 Enable HTTP API for automation and integration with other tools\n\n### Creating Persistent VMs\n\n```bash\n# Create a VM with persistent storage\nopenbsd-up 7.8 --image my-server.qcow2 --disk-format qcow2 --size 40G\n\n# Run a VM in the background\nopenbsd-up 7.8 --detach --image background-vm.img\n\n# Later, restart the same VM (no ISO needed for installed systems)\nopenbsd-up start \u003cvm-name\u003e\n\n# Monitor the VM logs\nopenbsd-up logs \u003cvm-name\u003e --follow\n```\n\n## 🌐 HTTP API\n\n`openbsd-up` includes a RESTful HTTP API server for programmatic VM management:\n\n```bash\n# Start the API server (default port: 8891)\nopenbsd-up serve\n\n# Start on a custom port\nopenbsd-up serve --port 3000\n```\n\n### Authentication\n\nThe API uses Bearer token authentication. Set your token via environment\nvariable:\n\n```bash\nexport OPENBSD_UP_API_TOKEN=\"your-secret-token\"\nopenbsd-up serve\n```\n\nIf not set, a random token will be generated and displayed at startup.\n\n### API Endpoints\n\nThe API provides endpoints for managing:\n\n- **Machines**: `/machines/*` - Create, start, stop, list, and inspect VMs\n- **Images**: `/images/*` - Pull, push, tag, list, and remove images\n- **Volumes**: `/volumes/*` - Create, list, inspect, and remove volumes\n\n### Example Usage\n\n```bash\n# List all VMs\ncurl -H \"Authorization: Bearer your-token\" http://localhost:8891/machines\n\n# Start a VM\ncurl -X POST -H \"Authorization: Bearer your-token\" \\\n  http://localhost:8891/machines/my-vm/start\n\n# List volumes\ncurl -H \"Authorization: Bearer your-token\" http://localhost:8891/volumes\n```\n\n## 📝 Configuration File\n\nCreate a `vmconfig.toml` file to define default VM settings:\n\n```bash\n# Initialize configuration file\nopenbsd-up init\n```\n\nExample `vmconfig.toml`:\n\n```toml\n[vm]\niso = \"https://cdn.openbsd.org/pub/OpenBSD/7.8/amd64/install78.iso\"\ncpu = \"host\"\ncpus = 4\nmemory = \"4G\"\nimage = \"openbsd.qcow2\"\ndisk_format = \"qcow2\"\nsize = \"40G\"\n\n[network]\nport_forward = \"2222:22,8080:80\"\n\n[options]\ndetach = false\n```\n\nOnce configured, simply run `openbsd-up` to start the VM with your settings.\n\n## 🔧 Architecture\n\nBuilt with modern TypeScript and Deno, featuring:\n\n- **CLI Framework**: [Cliffy](https://cliffy.io/) for robust command-line\n  interface\n- **HTTP Framework**: [Hono](https://hono.dev/) for fast and lightweight API\n  server\n- **Database**: SQLite with [Kysely](https://kysely.dev/) query builder for\n  type-safe operations\n- **State Management**: Persistent VM state tracking with migrations\n- **Dependencies**: Minimal runtime dependencies, leveraging Deno's built-in\n  capabilities\n- **Unique IDs**: CUID2 for collision-resistant VM identifiers\n- **Human Names**: Moniker for memorable VM names\n\n## 📄 License\n\nSee [LICENSE](LICENSE) file for details. Licensed under Mozilla Public License\nv2.0.\n\n## 🤝 Contributing\n\nIssues and pull requests welcome!\n\n---\n\nMade with 🐡 for OpenBSD enthusiasts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsirysndr%2Fopenbsd-up","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsirysndr%2Fopenbsd-up","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsirysndr%2Fopenbsd-up/lists"}