vmette

Run your coding agent on your Mac — without the anxiety.

Claude Code, Cursor, Cline, and friends pip install whatever a README names, execute model output, and act on web pages that can carry prompt injection. Run that straight on your laptop and the agent has your files, your tokens, and your network. vmette gives that work somewhere safe to happen instead: a real, hardware-isolated Linux VM that boots in ~1 second, sees only what you share in, and disappears when it's done. Send the agent's untrusted work there — or lock the agent down so the VM is its only way to run code — and nothing it executes ever touches your real machine.

It's built on Apple's Virtualization.framework: the boundary is a hypervisor with its own kernel, not a container sharing yours. And it's a Model Context Protocol server, so any MCP-aware agent host gets a sandboxed machine with one line of config.

Why on-device

The cloud sandboxes are just as well-isolated — the difference is keeping that isolation on-device: no round-trip, no meter.

Install

curl -fsSL https://github.com/chamuka-inc/vmette/releases/latest/download/install.sh | bash

Installs to ~/.local/share/vmette/ (the C ABI lands at lib/libvmette.dylib + include/vmette.h there), symlinks ~/.local/bin/{vmette,vmetted,vmette-mcp}. macOS-only (requires Apple's Virtualization.framework).

git clone https://github.com/chamuka-inc/vmette
cd vmette
make build              # cargo build + codesign
make test               # cargo unit + end-to-end VM smoke

Give your agent a sandbox (MCP)

vmette-mcp is a Model Context Protocol server that hands any MCP-aware agent host a sandboxed machine as a set of tools (execute, fetch_url, workspace_*, desktop_*). Work the agent runs through these tools happens inside the VM, confined as above. Note it adds the sandbox alongside the host's own tools; in Claude Code the agent still has native Bash that runs on your Mac, so to make the VM its only way to run code, restrict those too (e.g. deny the Bash tool).

Claude Code — one command, no config file:

claude mcp add vmette --scope user -- vmette-mcp --allow-network

Claude Desktop, Cursor, Cline, Zed, Goose — point the host at the vmette-mcp command. JSON example (Claude Desktop's ~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": {
    "vmette": {
      "command": "vmette-mcp",
      "args": ["--default-image", "python:3.12-alpine", "--allow-network"]
}}}

Each execute and workspace_run call boots a fresh microVM; a workspace is a persistent host directory mounted into each run, so files survive across calls (workspace_create/write/read/destroy are host-side directory ops). execute picks its image from the requested language; --default-image only sets the rootfs for workspace_create.

Full tool reference, per-host configs, and the security model: docs/MCP.md.

Give your agent a desktop (computer use)

Drive a persistent graphical Linux desktop inside a microVM — screenshot, click, type — the way a computer-use agent expects. A headless X server (Xvfb) + window manager run in the guest, driven by an in-guest agent over vsock; no Apple graphics window is involved.

vmetted &                                    # sessions live in the daemon
SID=$(vmette desktop start)                  # first run pulls the desktop rootfs from ghcr
vmette desktop screenshot "$SID" --out shot.png && open shot.png
vmette desktop exec "$SID" 'xterm &'
vmette desktop click "$SID" 640 400
vmette desktop type  "$SID" 'echo hello'
open "$(vmette desktop view "$SID")"        # watch & drive it live over VNC
vmette desktop stop  "$SID"

You can watch — and take over — a session live: vmette desktop view (or the desktop_view MCP tool) returns a loopback vnc://host:port you open with any VNC client (macOS Screen Sharing via open vnc://…). The daemon streams the screen and forwards your mouse/keyboard as the same actions the agent uses, so a human and the agent share one display. The same capability is exposed to agents through the MCP desktop_* tools (desktop_screenshot returns a PNG image block).

The desktop rootfs. The desktop needs a GUI rootfs — an X server (Xvfb) and a window manager. You don't have to build one: vmette desktop start auto-pulls the published default on first use (no Docker), and the computer-use agent is host-injected (a static binary vmette ships), so any GUI image works. See docs/DESKTOP.md for the resolution order and bring-your-own recipe.

See docs/DESKTOP.md for the session lifecycle, protocol, action reference, and image build.

Run a one-off command (CLI)

Not running an agent? The same sandbox is a one-liner. Pull an OCI image and run a command in it:

vmette --rootfs python:3.12-alpine \
       --exec 'python3 -c "print(2**32)"; exit 0'

The exit code propagates to the host. The kernel and initramfs are auto-discovered (the release tarball ships them under $PREFIX/assets; from a checkout vmette finds ./assets). Override with --kernel / --initramfs or $VMETTE_ASSETS_DIR. First run pulls + extracts the image (python:3.12-alpine ≈ 30 s); subsequent runs are cache hits (~3 s), cached at ~/Library/Caches/vmette/oci/.

One --rootfs flag, four sources — a local directory, an OCI ref, a tarball URL, or a squashfs block image. List the providers with vmette providers:

vmette --rootfs ./assets/aarch64/alpine-rootfs      --exec 'uname -a'
vmette --rootfs alpine:3.20                         --exec 'cat /etc/alpine-release'
vmette --rootfs oci://ghcr.io/foo/bar:v1            --exec '/run-tests.sh'
vmette --rootfs tar+https://h/builds/r.tar.gz       --exec 'make ci'
vmette --rootfs tar+file:///tmp/local-rootfs.tar    --exec 'ls /'
vmette --rootfs squashfs+file:///tmp/base.sqfs      --exec 'ls /'

Network is off until you ask (--net), virtio-fs shares only the host dirs you name, and the rootfs can attach read-only. Private OCI registries authenticate via env vars or ~/.docker/config.json (VMETTE_OCI_AUTH_<HOST>=user:secret or VMETTE_OCI_TOKEN). Full flag list: vmette --help or docs/CLI.md.

The writable root is a RAM-backed overlay by default, so a heavy build or extract can outgrow --mem-mib and hit No space left on device. Add --scratch SIZE (e.g. --scratch 8G) to back it with an ephemeral ext4 disk instead — sized independently of RAM, created sparse per run, and discarded on teardown:

vmette --rootfs rust:1.80 --net --mem-mib 1024 --scratch 8G \
       --share src=$PWD --exec 'cd /mnt/src && cargo build'

How it works

1. vmette builds a VZVirtualMachineConfiguration (kernel, initramfs, virtio devices, vsock).
2. The kernel command line carries only vmette.boot=ctl (plus vmette.vsock_port when vsock is on). Everything per-invocation — exec (base64 as VMETTE_EXEC_B64), env, rootfs mode, shares, scratch device, switch-root, and net — travels in a typed boot.env envelope written to a ctl virtio-fs share. The guest's /init (scripts/custom-init.sh) sources that envelope in pure shell, mounts virtio-fs shares, brings up the network if requested, then chroot / switch_root into the rootfs and runs the command.
3. After the command exits, the guest writes the code to .vmette-exit, syncs, and poweroff -f. VZ fires the lifecycle delegate; the host reads the file and exits with that code.
4. An immutable squashfs rootfs attaches read-only as virtio-blk with a tmpfs overlay, so the base stays content-addressable and shareable across sessions.

Embed it

vmette is also a library. The same VM primitive is available as a Rust crate, a C-ABI dynamic library, and a long-lived daemon — for building your own agent host or sandbox tooling on top.

The library accepts a directory path; resolution from a spec (OCI ref, tarball URL, …) goes through the provider registry first.

use vmette::provider::Context;
use vmette::Config;

fn main() {
    // The standard registry, in the load-bearing resolution order the CLI and
    // daemon use. To customize, hand-build one instead:
    //   use vmette::provider::{DirProvider, Registry};
    //   Registry::new().with(DirProvider::new()).with(/* … */);
    let registry = vmette_providers::default_registry();
    let ctx = Context::new(vmette_assets::default_cache_root()); // $HOME/Library/Caches/vmette
    let artifact = registry.resolve("alpine:3.20", &ctx).unwrap();

    let mut cfg = Config::new("./assets/aarch64/vmlinuz-virt", "./assets/aarch64/initramfs-vmette");
    cfg.set_rootfs_artifact(artifact, false);
    cfg.exec_cmd = Some("echo hello from rust; exit 42".into());

    // run() blocks until guest poweroff and process-exits with the guest's code.
    let _ = vmette::run(&cfg);
}

[dependencies]
vmette           = "0.10"
vmette-providers = "0.10"  # default_registry(); pulls in the oci/tar/squashfs providers
vmette-assets    = "0.10"  # default_cache_root() + boot-asset discovery helpers

See crates/vmette/examples/minimal.rs and docs/API.md.

#include "vmette.h"

int main(int argc, char **argv) {
    vmette_config_t *cfg = vmette_config_new(argv[1], argv[2]);
    vmette_config_set_rootfs_share(cfg, argv[3], false);
    vmette_config_set_exec(cfg, "echo hello from C; exit 11");
    vmette_run_output_t *out = NULL;
    vmette_run(cfg, &out);                /* exits on guest poweroff */
    return vmette_run_output_exit_code(out);
}

cc -I include -L lib -lvmette -Wl,-rpath,lib -o demo demo.c

The -Wl,-rpath,lib matters: libvmette.dylib has the install name @rpath/libvmette.dylib, so the binary needs an rpath pointing at the directory that holds the dylib. The header is auto-generated from crates/vmette/src/ffi.rs via cbindgen and checked in at crates/vmette/include/vmette.h. See crates/vmette/examples/minimal.c and docs/API.md.

vmetted &

Listens on ~/Library/Caches/vmette/vmette.sock. Speaks line-delimited JSON: client sends one request object, daemon streams stdout frames (guest stdout and stderr combined) followed by a terminal exit frame. Useful for amortizing per-invocation cost or driving many runs from a long-lived caller; it also owns the stateful desktop session registry and the live VNC view.

import socket, json
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect("/Users/me/Library/Caches/vmette/vmette.sock")
s.sendall((json.dumps({
    "kernel": "/abs/path/vmlinuz-virt",
    "initramfs": "/abs/path/initramfs-vmette",
    "rootfs": "/abs/path/alpine-rootfs",   # also accepts alpine:3.20, tar+https://..., etc.
    "exec": "echo from daemon; exit 17",
}) + "\n").encode())
s.shutdown(socket.SHUT_WR)
print(s.recv(65536).decode())

See docs/DAEMON.md.

Constraints

• macOS only. VZ is Apple-private. No Linux/Windows port planned.
• Guest assets are architecture-specific. Apple Silicon uses Alpine aarch64; Intel uses x86_64. Runtime discovery checks the per-arch assets/<arch>/ directory under each search root.
• Snapshot/restore is Apple-Silicon-only. Apple gates the save/restore calls behind #if defined(__arm64__). On Intel, --build-snapshot / --resume-snapshot return VmetteStatus::SnapshotUnsupported. The daemon's snapshot-warm-pool is a planned optimization, not yet implemented.
• Desktop sessions are software-rendered and live in the daemon. Headless Xvfb (no GPU); each session is a 2 GB (2048 MiB) VM, capped and idle-evicted. Fine for agentic GUI control and UI testing, not for video / WebGL / 3D. See docs/DESKTOP.md.

Docs

• docs/MCP.md — vmette-mcp server tool reference + client configs
• docs/DESKTOP.md — desktop computer use: sessions, protocol, image build
• docs/CLI.md — full flag reference
• docs/API.md — Rust + C library API
• docs/DAEMON.md — vmetted protocol spec
• docs/HACKING.md — build, test, debug, repo layout
• CHANGELOG.md — release notes

License

MIT. See LICENSE.