Alpha Software -- BarkVisor is under active development. APIs, configuration, and behavior may change rapidly between releases. Use at your own risk and expect breaking changes.
A headless daemon for managing QEMU virtual machines through a web UI.
Platforms:macOS (.pkg / HVF) and Linux (packages + systemd / KVM). See Linux install.
In the UI, the machine running BarkVisor is a Device in your Home — not a node or a cluster. Product terminology.
- Create, start, stop, and manage VMs with configurable CPU, RAM, disks, and networks
- UEFI boot and TPM 2.0 support
- Cloud-init provisioning with user data templates
- Deploy VMs from templates, synced from remote catalogs
- qcow2/raw disk management with hot-plug and online resize
- NAT networking with port forwarding; bridged networking on macOS (socket_vmnet) and Linux (host bridge + qemu-bridge-helper)
- OS image library with HTTP download and auto-decompression (arm64 and x86_64)
- Live CPU, memory, and disk I/O metrics
- Serial console (wterm) and VNC display (NoVNC) in the browser
- JWT authentication, API keys, and audit logging
- SSH key management for VM injection
- Database backups, log rotation, and diagnostic bundles
- USB passthrough (macOS and Linux via
usb-host)
- macOS 26+ (Apple Silicon only for HVF guests today)
- Xcode with Swift 6 toolchain
- Bun (for the frontend)
- Homebrew
Install build dependencies:
brew install meson ninja pkg-config glib pixman dylibbundler \
gnutls jpeg-turbo libpng libssh libusb zstd lzo snappy \
autoconf automake libtool json-glib swiftlint swiftformatInstall a prebuilt.deb / .rpm / tarball from Releases, plus distro QEMU/firmware. Full steps: Installation (Linux).
# Example (Debian/Ubuntu amd64) after installing QEMU/OVMF from the distro:
sudo dpkg -i barkvisor_*_amd64.deb
sudo systemctl enable --now barkvisor.service
# → http://localhost:7777swift build
swift run BarkVisorAppThe server starts on http://localhost:7777. On first launch a web-based setup wizard creates your admin account.
cd frontend
bun install
bun run devThe Vite dev server starts with hot reload, proxying API calls to the backend.
cd frontend
bun run buildThe built files go into Sources/BarkVisor/Resources/frontend/ and are served by the backend directly.
Use mise (see mise.toml) or raw Swift tools:
mise run build # swift build -c release
mise run test# swift test
mise run lint # swiftlint + swiftformat --lint
swiftformat Sources/ Tests/ # apply formatting# CI equivalent: mise run lint && mise run testcd frontend
bun run cy:open # Interactive Cypress
bun run test:e2e # Headless CypressDownload the latest .pkg from the releases page and install:
sudo installer -pkg BarkVisor-<version>.pkg -target /This can also be done entirely over SSH on a remote Mac -- no GUI required.
After installation, open http://<host-ip>:7777 in a browser to complete setup.
To uninstall:
sudo ./scripts/uninstall.sh # keep data
sudo ./scripts/uninstall.sh --purge # remove everythingDownload .deb / .rpm / .tar.gz from the releases page and follow Installation (Linux). Building packages from source is optional (see that guide or Development).
The release script compiles QEMU, swtpm, socket_vmnet, and xz-utils from source, builds the frontend, compiles the Swift app, assembles the daemon install layout, and creates a .pkg installer.
# Required: Apple Team ID for XPC code-signing verificationexport APPLE_TEAM_ID=YOUR_TEAM_ID
# Optional: signing identity for distributionexport SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
./scripts/build-release.shOptions:
| Flag | Effect |
|---|---|
--skip-deps | Reuse cached dependency builds |
--no-sign | Skip code signing |
--no-pkg | Skip installer .pkg creation |
--require-notarize | Fail if notarization credentials are missing |
The output is build/stage/ (install layout), build/BarkVisor-<version>-standalone.tar.gz, and build/BarkVisor-<version>.pkg.
macOS: installed daemon data is under /var/lib/barkvisor/; development builds use ~/Library/Application Support/BarkVisor/.
Linux: development default is ~/.local/share/barkvisor; installed layout uses /var/lib/barkvisor (see Linux guide). Override with BARKVISOR_DATA_DIR / BARKVISOR_PORT / BARKVISOR_FRONTEND_DIR.
| Path | Contents |
|---|---|
db.sqlite | Application database |
jwt-secret | Auto-generated JWT signing key |
disks/ | VM disk images |
images/ | Downloaded OS images |
logs/ | Application logs |
backups/ | Database backups |
The server listens on port 7777 by default, bound to 0.0.0.0.
Website (landing + docs, one deploy): cd website && bun install && bun run build → website/dist/. Deploy: bun run deploy (Cloudflare Pages). See website/README.md.
- Installation (macOS) — System requirements,
.pkginstall, SSH install, data directory - Installation (Linux) — System requirements,
.deb/.rpm/ tarball, systemd, data directory - First Launch and Setup — Web-based setup, admin account, bridge helper (macOS) vs host bridge (Linux)
- Quickstart — Create and run your first VM (arm64 / x86_64)
- Development Setup — Build from source, dev workflow, testing
- Building Releases — macOS release script + Linux package builds
- Troubleshooting — Common issues and solutions
MIT License. See LICENSE for details.