Crate vmette 

vmette — local Linux microVM sandbox for macOS via Virtualization.framework.

This crate is the host-side library. It wraps Apple’s Virtualization framework via objc2-virtualization and exposes a Rust API for booting a Linux guest with virtio-fs shares, virtio-blk disks, virtio-net, vsock, and a base64-encoded shell command delivered via the kernel cmdline.

See Config for the configurable surface and run for the synchronous entry point.

Re-exports

pub use error::Error;

pub use provider::BlockFs;

pub use provider::RootfsArtifact;

Modules

desktop

Desktop computer-use protocol: the framed request/response codec that carries the crate::Action vocabulary between the host crate::Session (Agent workload) and the in-guest vmette-desktop-agent.

error

ffi

C ABI for the vmette library.

provider

Pluggable rootfs providers.

Structs

Config

One-shot VM configuration. Build with Config::new, populate public fields, then pass to run.

ResponseHeader

JSON header of a response frame (guest → host). ok reports success; on failure error carries a message and no payload follows. x/y are populated by Action::CursorPosition. payload_len is the count of binary bytes (e.g. PNG) following this header in the frame.

RootfsBlock

A filesystem image attached as virtio-blk slot 0 (/dev/vda) and mounted read-only as the lower layer of a tmpfs-backed overlay root. Mutually exclusive with RootfsShare.

RootfsShare

Host directory exposed as the guest’s /.

RunOutput

Result of a completed run. Currently only carries the exit code, but kept as a struct so we can grow it without breaking callers.

Session

A booted VM and everything that must outlive its dispatch queue.

SessionClient

Send handle for issuing desktop Actions against a live session from a thread other than the one that owns the Session. The data path is plain blocking read/write on the accepted vsock fd, independent of the VM’s dispatch queue.

ShareMount

The one workspace-wide host-directory share descriptor, owned by vmette-proto so the daemon’s run protocol and this config API share a single type. Re-exported here as part of the core’s public surface. A host directory exposed to the guest: <tag> → <path>. The single share-descriptor type for the whole workspace (re-exported as vmette::ShareMount for the core config API and used by crate::daemon::Request).

StopHandle

Send handle for stopping a live session from another thread. Holds a reference to the VM and its queue; all fields are Send, so the handle is Send without an explicit unsafe impl.

Enums

Action

A single computer-use action sent host → guest. Serialized as the JSON header of a request frame (no payload). Variants mirror the Anthropic computer-use tool so the MCP layer maps 1:1.

ScrollDirection

Scroll wheel direction for Action::Scroll.

SessionEnd

How a session ended. The first writer into the [EndSlot] wins, so a timeout that races a natural poweroff reports TimedOut.

VsockPort

Per-invocation host vsock port policy.

WorkloadStrategy

Selects what the guest does once booted, and therefore which terminal event ends the Session.

Functions

run

Boot the configured guest, exec the command, block until poweroff, then exit the process with the guest’s exit code.