Berry Wiki

Quickemu

Properties2
tagsai, sandboxing
aliasesQuickemu

7 min read

Quickemu

Summary

Quickemu is a mature command-line wrapper around QEMU. It downloads operating-system images, creates sensible virtual-machine configurations, and launches full Windows, macOS, Linux, BSD, and other guests with little manual QEMU work.

Problem

QEMU can provide strong virtual-machine isolation, but its many settings make setup slow and error-prone. Quickemu automates image selection and chooses host-specific defaults so a developer can create a full machine with two commands.

How It Works

  • Image setup: quickget downloads an upstream operating-system image and creates a plain-text VM configuration.

  • Optimized launch: quickemu inspects the host and converts that configuration into suitable QEMU options.

  • Full VM: The guest receives its own kernel, virtual disk, memory, processors, network adapter, and devices.

  • Persistent state: The virtual disk keeps installed tools, source code, and agent state between runs.

  • Host integration: Optional SPICE clipboard, shared folders, USB devices, smartcards, SSH forwarding, and network port forwarding make desktop use convenient.

Security Boundary

  • Separate guest kernel: Commands inside the guest do not run in the host kernel. On Linux, QEMU normally uses KVM hardware virtualization when available; it can emulate processors when needed.

  • Large device surface: QEMU models a complete computer. Graphics, clipboard, shared files, USB devices, guest agents, and other integrations add paths across the boundary.

  • Shared files remain exposed: Quickemu’s automatic sharing exposes the current user’s ~/Public folder. Anything shared or passed through should be treated as available to hostile guest code.

  • Host reachable by default: QEMU user networking uses 10.0.2.2 for the host. A guest can connect to host services through that address unless networking or host services are restricted.

  • Escape risk remains: QEMU and its device models can have vulnerabilities. Quickemu simplifies configuration but does not claim to harden QEMU for untrusted AI agents.

  • No agent policy layer: Quickemu does not add command approval, secret filtering, filesystem allowlists, or agent-specific audit logs.

Platforms and Agents

  • Hosts: Linux and macOS.

  • Guests: Nearly 1,000 editions across Linux, Windows, macOS, BSD, FreeDOS, Haiku, ReactOS, and other systems.

  • Architectures: ARM64 guests can run natively on ARM64 hosts or through emulation on x86-64 hosts.

  • Agents: No coding agent is bundled. Claude Code, Codex, or another command-line agent must be installed and configured inside the guest.

Setup

  • Install: Packages are available for several Linux distributions, Homebrew, Nix, and NixOS. A Debian package and source installation are also documented.

  • Requirement: Release 4.9.9 requires QEMU 6.1 or newer. Source installs need QEMU plus several command-line utilities.

  • Create: Run quickget with the desired operating system, release, and edition.

  • Start: Run quickemu --vm <configuration-file>.

  • Agent preparation: Complete the guest installation, install the agent and project tools, then place or clone the repository inside the VM.

Network and Credentials

  • Default network: QEMU user-mode networking gives the guest outbound TCP/IP access through a private 10.0.2.0/24 network.

  • Host access: The guest gateway at 10.0.2.2 connects to services on the host.

  • Offline mode: --offline or network="none" disables guest networking.

  • Restricted mode: network="restrict" keeps a virtual network but blocks access to the host and broader network.

  • Broader options: Bridged networking places the guest on a configured host network. Explicit port forwarding maps host ports to guest services.

  • Credentials: Quickemu has no credential broker. Users must enter keys in the guest, use its credential manager, or deliberately share files and devices.

  • Safer pattern: Create separate, narrowly scoped credentials inside the VM. Avoid sharing a host home directory, SSH directory, or cloud configuration.

Strengths

  • Mature QEMU base: A full hardware-backed VM offers a stronger default boundary than a normal process or shared-kernel container.

  • Broad compatibility: The large guest catalog supports tools that need a complete Linux, Windows, or macOS environment.

  • Simple workflow: Two main commands replace extensive QEMU configuration.

  • Useful network controls: Fully offline and restricted modes are built in.

  • Persistent and inspectable: VM configuration and disk files can live anywhere, including external storage, without requiring elevated permission to run.

  • Active community: The project has years of history, thousands of stars, regular releases, and active development.

Limits

  • Not agent-specific: There is no automatic repository mount, safe credential injection, hostname allowlist, session cleanup, or agent lifecycle management.

  • Heavyweight: Full operating-system installation, boot, updates, disk storage, and memory use are greater than purpose-built microVM sandboxes.

  • Permissive defaults: Normal networking reaches both the internet and host services. Agent users must opt into offline or restricted networking.

  • Integration tradeoff: Clipboard, shared folders, USB pass-through, and guest-agent features improve convenience while widening the attack surface.

  • Image trust: quickget downloads third-party operating-system material. Integrity handling varies by source, so high-trust use should verify the specific image and publisher chain.

  • macOS constraints: Guest compatibility, performance, and Apple licensing require separate review.

Activity and Maturity

Checked 2026-07-14.

  • History: The repository was created in March 2020 and showed 2,306 commits.

  • Current activity: GitHub reported a push on 2026-07-14. The newest default-branch commit returned by the API was 82df57dadfd415e7ee3e54aff2b21cde1df7e93e, merged on 2026-06-19.

  • Latest release: Version 4.9.9, published 2026-02-10, added ARM64 guest support and performance, display, and platform improvements.

  • Community: About 15,282 stars, 681 forks, and 83 watchers.

  • Open work: GitHub’s combined issue and pull-request count was 58; the repository page showed roughly 41 issues and 16 pull requests.

  • Assessment: Established and actively maintained, but maturity as a desktop-VM launcher does not equal a reviewed agent-sandbox security profile.

Best Fit

  • Good fit: Developers who want a reusable full operating system for an agent and value compatibility over instant startup.

  • Good fit: Cross-platform testing, GUI automation, and tools that cannot run in a minimal Linux sandbox.

  • Good fit: Offline agent work in a manually prepared VM with no host shares and limited credentials.

  • Poor fit: Fast disposable agent sessions, automatic per-task environments, strict hostname filtering, or managed secret delivery.

Comparison

  • Versus Clawk: Quickemu supplies general-purpose persistent VMs. Clawk packages short-lived microVMs around coding agents, repositories, filtered networking, and task workflow.

  • Versus SandBoxy: Both use separate guest kernels. SandBoxy targets agent sessions and starts cached microVMs quickly; Quickemu supports many complete desktop operating systems but needs more setup and manual policy.

  • Versus AgentVM: Quickemu uses native QEMU virtualization and mature operating systems. AgentVM embeds Linux-as-WebAssembly in Node with a smaller API but an explicitly experimental security foundation.

  • Versus Docker: Quickemu isolates with a separate kernel and supports non-Linux guests. Docker is faster and lighter for repeatable Linux tool environments.

Hacker News Context

Quickemu appeared in the Clawk discussion as an existing way to place agent work inside a virtual machine. It supports the broad idea that developers can isolate risky tools with established VM software, while lacking Clawk’s agent-specific setup, network allowlist, and short-lived workflow.

Direct Sources

Unknowns

  • Agent hardening: No official threat model or recommended configuration for hostile coding agents was found.

  • Image verification: The exact signature or checksum chain for every supported operating-system source was not assessed.

  • Host filtering: The practical host-service exposure under each QEMU networking mode needs testing on the chosen host platform.

  • Share permissions: Read-only controls and exact behavior vary among Samba, SPICE WebDAV, and VirtIO-9p and need per-guest validation.

  • Snapshots: The official overview does not present a simple, agent-focused disposable snapshot workflow.

  • Resource enforcement: CPU and memory sizing are configurable, but a documented hostile-workload resource policy was not found.

  • Independent audit: No independent security audit of Quickemu’s generated configurations was found.

Sources

    • imported AI research note for Quickemu.

Graph View