Berry Wiki

Virtdev

Properties2
tagsai, sandboxing
aliasesVirtdev

8 min read

Virtdev

Checked: 2026-07-14

Project Summary

Virtdev creates one lightweight, disposable Arch Linux virtual machine (VM) per development project. Each VM uses QEMU/KVM hardware virtualization and stores only its changes on top of a shared, sealed base image.

  • License: AGPL-3.0
  • Implementation: Mostly shell scripts, plus a small C helper
  • Host: Arch Linux with an x86 KVM-capable processor
  • Guest: A minimal, headless Arch Linux system
  • Main focus: Protect the trusted host and other projects from compromised dependencies and unsafe development work

Problem Solved

Virtdev reduces the risk that an npm, pip, Cargo, or similar supply-chain attack can read host files, steal host credentials, alter other projects, or stay on the main system.

It also makes full VMs practical for daily work by sharing one base system. Think of the base as a master stencil: each project records only its own changes instead of copying the whole machine.

How It Works

  1. Build and install one minimal Arch Linux base image.
  2. Seal the base images as read-only.
  3. Create each project as two thin qcow2 copy-on-write disks over that base:
    • a system disk for the operating system and packages;
    • a home disk for /home/dev and project work.
  4. Run each VM as a transient systemd --user service.
  5. Connect through SSH on a host-loopback port.
  6. Recreate a VM through a backup, destroy, create, provision, and restore sequence when the base changes.

The project provides lifecycle, inspection, transfer, backup, restore, maintenance, upgrade, firewall, console, and QEMU monitor commands.

Security And Isolation Boundary

  • Primary boundary: A hardware-assisted KVM/QEMU hypervisor, not a shared-kernel container, namespace, or language permission system.
  • Intended protection: Host-to-guest and project-to-project isolation.
  • Default network state: none, which permits the host’s SSH connection but blocks guest destinations.
  • Host controls policy: The guest cannot select its own network zone. The host selects it at launch.
  • SSH hardening: Public-key-only login, locked accounts, no root login, loopback-only forwarding, and an isolated client configuration that deliberately ignores the user’s global SSH config.
  • Privileged exception: Applying the host nftables firewall requires root once and after custom-zone changes. Starting a VM refuses when the firewall is inactive unless the user explicitly chooses --unfiltered.

This is a stronger boundary than a normal container, but it is not absolute. A QEMU/KVM escape, a deliberately opened host service, or misuse of the unfiltered override can cross or weaken it.

Supported Platforms And Agents

  • Supported host: Arch Linux only, with Bash 5.3+, KVM, QEMU x86, OVMF, OpenSSH, passt, nftables, socat, rsync, and archiso.
  • Other hosts: macOS, Windows, other Linux distributions, ARM hosts, and remote/cloud hosts are not documented as supported.
  • Coding agents: The documentation explicitly names Claude Code as a normal WAN-connected workload. Virtdev is otherwise agent-neutral because agents run inside a regular Linux VM over SSH.
  • Agent integrations: No dedicated Claude Code, Codex, editor, Model Context Protocol, or agent-control integration is documented.

Workflow And Setup

Install from the Arch User Repository as virtdev-git, or build from source. Initial setup requires generating an SSH key, building an Arch installer image, installing the base, sealing it, and applying the firewall.

For each project:

  1. Create the VM.
  2. Start it in the required network zone.
  3. Wait for SSH.
  4. Connect and develop.
  5. Use a project provision script to make rebuilding repeatable.
  6. Put state that must survive recreation in an explicit backup manifest.

The sealed base is maintained centrally. After it is resealed, attached project deltas are rejected through a generation check and must be recreated. A project can instead be detached into standalone images and maintained separately.

Network And Credential Handling

Network

Virtdev uses passt for user-space networking and a host-root nftables filter tied to the VMs’ systemd control groups.

Built-in zones are:

  • none: No guest destination access beyond the SSH response path.
  • wan: Internet allowed; host and local network blocked.
  • lan: Host and local network allowed; internet blocked.
  • full: Internet, host, and local network allowed.

Custom zones can open selected host ports on top of a base zone. This is a port-level host exception, not a domain allow-list. The README says wan is the usual zone for package managers and Claude Code.

Credentials

  • VM access key: Virtdev generates and stores its own Ed25519 SSH key on the host and injects the public key into the guest base.
  • Host credentials: The global host SSH configuration is excluded so settings such as SSH agent forwarding do not leak into an untrusted VM.
  • Agent/API credentials: Secure host-to-guest credential injection is not implemented in the documented workflow. In the Hacker News discussion, the author said it was on the roadmap.
  • Outbound secrets: Once a credential is placed inside a guest with wan or full access, Virtdev does not claim to prevent internet exfiltration. Destination-level exfiltration control was described in the discussion as future work involving a custom network stack.

Strengths

  • Strong practical boundary: Uses a full hypervisor boundary for untrusted project code.
  • Cheap project VMs: Thin qcow2 deltas avoid copying the complete base for every project.
  • Secure network default: New projects default to no destination access.
  • Fine host control: Built-in zones and custom host-port holes cover more cases than a single network on/off switch.
  • Fail-closed behavior: Launch and firewall paths document refusal when required security state cannot be confirmed.
  • Reproducible rebuilding: Provision scripts, selected-file backups, restore, and generation checks support expendable machines.
  • Correct background lifecycle: VMs run under the user’s systemd manager instead of hand-managed background processes.
  • Detailed threat model: The design document openly records assumptions, failure modes, and known gaps.

Limits And Risks

  • Narrow platform support: Arch Linux and KVM/QEMU x86 requirements exclude many developer laptops.
  • High initial setup cost: Users build an installer and base system, then install a privileged firewall component.
  • Single-user firewall design: The firewall currently protects one selected host user; multi-user hosts are listed as future work.
  • No credential broker: Safe short-lived credential injection is not yet built in.
  • No hostname allow-list: Built-in policy filters broad network areas or selected host ports, not named internet services.
  • Internet exfiltration remains possible: The threat model prioritizes protecting the host and projects, not stopping secrets already placed in an internet-enabled guest from leaving.
  • Base updates require rebuilding: Attached project VMs must be recreated after resealing the base.
  • Backup is selective: Users must list files to preserve; compression, encryption, retention, and full-disk backup are not provided.
  • Documented unfinished work: Read-only-root mode is not tested end to end, and home-disk portability lacks commands.
  • Small project: Bus factor appears to be one. There were no open issues and no published release information visible through the repository metadata when checked; low issue counts are not proof of production readiness.
  • Hypervisor risk remains: VM isolation raises the escape difficulty but cannot make escape impossible.

Project Activity And Current Maturity

  • Created: 2026-04-02
  • Latest push: 2026-07-05
  • Repository state on 2026-07-14: 460 commits shown by GitHub, 6 stars, 1 fork, 0 open issues, default branch master, not archived
  • Recent work: July commits continued improving fail-closed firewall and lifecycle behavior and their documentation.
  • Maturity assessment: Actively developed but early and specialized. The large command surface and detailed threat model are promising, while the short project history, small user signal, missing credential flow, unfinished features, and lack of documented stable releases argue for testing it as an experimental personal tool before relying on it for critical work.

Best Fit

Virtdev fits a security-conscious Arch Linux developer who:

  • runs untrusted packages or coding agents locally;
  • wants each project isolated from the host and other projects;
  • accepts command-line setup and VM overhead;
  • values reproducible, disposable environments;
  • wants network zones and controlled host-port access;
  • can manage credentials inside each guest until a broker exists.

It is a weak fit for teams needing macOS/Windows support, a graphical interface, cloud execution, cross-platform configuration files, managed credentials, or turnkey editor and coding-agent integration.

Comparison-Relevant Facts

FactVirtdev
IsolationFull KVM/QEMU VM per project
Host operating systemArch Linux
Guest operating systemArch Linux
Storage modelShared sealed base plus per-project thin qcow2 deltas
Default networkNo guest destination access
Network policynone, wan, lan, full, plus custom host-port zones
Internet domain allow-listNot implemented
Host port forwardingSSH loopback forward; custom zones open selected host service ports
Credential injectionNot implemented; planned in HN comments
Agent supportAgent-neutral shell/SSH VM; Claude Code named in docs
LifecycleUser-mode systemd services
PersistenceWritable deltas; selected-file backup and restore; optional detachment
ReproducibilityShared sealed base plus user-written provision scripts
Root requirementFirewall apply and custom-zone realization; VM use is otherwise designed around user services
Configuration styleCommands and dotfiles/scripts; deliberately not a declarative Vagrantfile/YAML model
LicenseAGPL-3.0

Hacker News Comment Context

Virtdev’s author introduced it in the Clawk discussion while asking how Clawk filters network traffic without root. Clawk’s author replied that macOS uses a file-handle network device and gvproxy, allowing a user-space allow-list before each host connection; Clawk’s Linux Firecracker path still uses sudo for the TAP device.

The Virtdev author described the project’s reason for existing as protection from package supply-chain attacks rather than distrust of the coding agent itself. The author emphasized:

  • KVM isolation;
  • cheap, disposable, contextual VMs through qcow2 deltas;
  • rollbacks;
  • a configurable nftables egress firewall;
  • user-mode systemd lifecycle management;
  • mechanism supplied by the tool, with user policy kept in dotfiles.

The same comments state that credential injection is missing, and that repository-aware application proxies, stronger destination controls, and credential management are planned. These are author roadmap statements, not current features.

Sources

Graph View