AgentVM app 1.1

New: Linux images and boxes, logs you can find, and Rename.

AgentVM.app is a Mac app for creating and managing AgentVM images and boxes: the virtual machines, running macOS or Linux, that AI coding agents run in, isolated from your Mac. It is a companion to the agent-vm and avm command line tools. Agents themselves run in Terminal (avm) or in Cadabra.

Highlights

• Linux images and boxes beside macOS ones: a first image in minutes with no macOS download, and boxes that start in seconds.
• Logs: every box, image and job says where its logs are, and the logs of a deleted box are kept for a while.
• Rename a box or an image from its pane.
• Get started no longer needs a macOS restore file: the first image can be a Linux one.
• agent-vm 0.7.46: the app follows the newest tools and installs them for you.

Linux images and boxes

A Linux box is for work that does not need a Mac. It starts in seconds, and its image is built without a macOS restore file.

• A first image without downloading macOS. New Image... lists the Linux systems your agent-vm builds, Debian 13 today. The image is made from the distribution's own cloud image, which agent-vm downloads and checks when it is needed. How long it takes is mostly the downloads: a few minutes on a fast connection.
• Tools. They are added as for a macOS image, by ticking recipes: in the same build, or later in a copy of the image. The window lists only the recipes that fit the system you start from.
• Boxes. A Linux box is made, started, stopped, recreated and deleted like a macOS box, with the same network rules and shared folder. Connect opens a shell in it and Run an Agent starts an agent in it. It has no screen, so it has no View.
• Updates. Update... on a Linux image installs the distribution's package updates, the tools' own updates and the newer guest daemon, the part of agent-vm that runs in the image.
• The kernel's memory pages. A Linux image is built with a kernel whose memory pages are 16 KiB, the Mac's own size, which keeps a box steady when the Mac runs short of memory. The image and box panes say which size each has.
• Told apart at a glance. The card of a Linux image or of a running Linux box is teal (a stopped box: slate), and every pane says which system an image or a box runs.
• Beside two macOS boxes. macOS runs at most two macOS virtual machines at once. Linux ones are not counted among them, and the app never holds a Linux box or build back for that limit.
• No Full Disk Access step. That permission exists only in a macOS image. A Linux image has none to grant, and nothing in its boxes waits for one.
• No Local Network question. macOS asks it during the first build of a macOS image only.

What the app leaves to agent-vm in Terminal:

• an image from a cloud image file of your own (image create --linux ... --cloud-image), and building an image again from a fresh start (image rebuild);
• a program run as root in a Linux box, such as installing a system package (agent-vm exec --user root);
• copying files into a box (box send).

The rest is in Docs/linux-boxes.md of the agent-vm repository.

Get started

• The restore file is no longer a step you must take. Step 3 says that one is needed only for a macOS image, and New Image... in step 4 works without it: start from a Linux system.
• Full Disk Access (step 5) is asked of macOS images only.

Logs

agent-vm records what it started in a box, what the box contacted and what was refused, in files on your Mac that nothing in a box can change. The app now shows where they are.

• A box and an image each have a Logs row in their pane: the box's log files in Finder or in Console, and for an image the log of the job that last built or updated it. A Linux image also has the console of its system.
• A build, an update or a start has Show Log in Finder in its progress window: every step and line of the job, which agent-vm keeps for a week.
• A deleted box leaves its logs behind, for 30 days unless you change it. Delete says so before you confirm. Settings says how many are kept and what they take, shows them in Finder, removes them, and sets for how long they are kept.
• Where the Logs Are..., in How to Use a Box, says which file answers which question and gives the Terminal commands that read them.

Rename

• A Rename button beside the name in a box's pane and in an image's pane opens a small window with the name in a field and the rule for names under it.
• A box can be renamed while it is stopped. It keeps what it holds, its network rules and its logs, and avm goes on using it for the folders it was used for.
• An image takes its boxes and the images built from it along at once: each names its image by the new name.
• When agent-vm refuses a name, for example one that is taken, the window shows its reason and stays open.

Builds and updates

• A notice stays until the job ends well. What agent-vm says before a step, for example about the Mac's memory before a boot, is no longer dropped when the next step begins: it stays in the progress window, marked "From an earlier step:", and is in the log too.
• A Linux build runs in two boots, the second on the 16 KiB kernel, and the progress window shows both.
• Update... says what an update now does first: a guest daemon ticked beside another part is replaced first and stays even if that part fails, and a tools update uses the newer recipe that came with the installed agent-vm.
• A macOS guest that starts again instead of powering off at the end of a build is asked to shut down again, and the build no longer fails for it.

Installing agent-vm

• Each version of agent-vm now installs beside the one before, so an update no longer takes the tools away from under boxes and jobs that are running. The app's Install... and Update... follow that.

Other changes

• The button for deleted boxes' logs is in Settings, not under the list of boxes.
• After an agent session in a kept box, avm asks whether to stop the box and lists what changed in the shared folder, with undo per entry. How to Use a Box says so.
• A new link opens the logs window:

open agentvm://logs            # the Where the Logs Are window

Good to know

• Debian is the one Linux system offered. Ubuntu 26.04 is left out for now: it has no kernel with 16 KiB memory pages, and a box on its 4 KiB kernel can lose memory and stop when the Mac runs short of it.
• Disk space. A Linux image needs no 27 GB restore file. Its disk is a sparse file, which takes only what is written to it, and a box shares what it did not change with its image.
• One agent-vm. Terminal, Cadabra and this app all run the copy in ~/.local/bin.

Requirements and installing

• A Mac with Apple silicon and macOS 27 or later. The app does not open anywhere else.
• agent-vm 0.7.46 or later. The app offers to install or update it.

Open AgentVM_1.1.zip and move AgentVM.app to the Applications folder, replacing version 1.0.

License

Apache License 2.0, as agent-vm.

AgentVM app 1.0

First release.

AgentVM.app is a Mac app for creating and managing AgentVM images and boxes: the macOS virtual machines that AI coding agents run in, isolated from your Mac. It is a companion to the agent-vm and avm command line tools. It guides you through setup and first use, then shows what exists and what runs, with the everyday actions one or two clicks away. Agents themselves run in Terminal (avm) or in Cadabra.

Highlights

• Get started: six steps from nothing to a first box.
• Images: build one from a macOS restore file or as a copy of another image, with the tools you choose. Then update it, open its screen, delete it.
• Boxes: make one from an image with the network it may reach. Then manage: start, stop, view, open a shell, run an agent.
• A box's network: the hosts it may reach, edited and applied in one step, and what it tried to reach.
• Long work runs as jobs: downloads and builds go on when a window, or the app, is closed, and each has a progress window.
• One source of truth: the app keeps no copy of what agent-vm knows, so what you do in Terminal or in Cadabra shows up here.

Get started

The main window opens on Get started until an image is ready. Its six steps:

1. agent-vm - the command line tool the app runs. Install... downloads the newest release, checks its signature and installs it for your account in ~/.local/bin. Update... does the same when the installed one is too old for the app.
2. This Mac can run boxes - what agent-vm's own check says, with Check Again.
3. A macOS restore file - Get macOS... shows the newest one Apple offers for this Mac and downloads it (about 27 GB).
4. An image - New Image... builds the first one, in about 10 minutes.
5. Full Disk Access - optional, see below.
6. A box - New Box... makes one in seconds.

When an image is ready the window changes to Boxes, Images and Settings.

Images

An image is the template: a sealed macOS with tools in it, which never runs itself.

• New Image works in five steps: what to start from, the tools, their options, the name and size, and a last check that shows the command about to run.
• Tools are recipes that come with agent-vm: Homebrew, Node, Python, agent command line tools, ACP (Agent Client Protocol) agents, Xcode and its platforms. They are installed in an order that satisfies what each needs, and the window says when one is missing.
• A recipe file of your own can be added to the list; agent-vm checks it first and the window shows what it warns about.
• Update... installs a newer macOS, refreshes the tools, or replaces the guest daemon after an agent-vm update.
• View opens the image's screen in a window, for setup by hand. What you do there is kept.

Boxes

A box is a working clone of an image, made in seconds, and it is what runs, using only the project folder you share and the hosts you allow.

• New Box: the image, the name and size, and the network mode: Allowlist (only the hosts you list), Open or Off. Named sets of hosts (packs) add the hosts a tool needs in one click.
• Start and Stop, View (its screen), Open Shell and Run an Agent in Terminal... from the box's pane.
• Recreate makes a box again from its image as the image is now; Delete removes it. Both ask first and say what is lost.
• Needs maintenance marks a box made before its image changed, and an image with a newer macOS or guest daemon to take. The pane says what to do.
• How to Use a Box... shows the commands for Terminal, ready to copy.

A box's network and programs

• Network > Settings: the rules of the box, edited as a list and applied in one step.
• Network > Activity: the connections the box made or was refused, grouped by host, with Allow Selected Host for one that was refused.
• Programs: what ran in the box, newest first, with each program's status, and the ones that waited on a question macOS asked on the box's screen.

Jobs and progress

Starting or stopping a box, building or updating an image and downloading a restore file run as agent-vm jobs. They go on when you close the window or quit the app.

• Each job has a progress window: its steps, a bar when agent-vm reports how far it is, the end of its log, and Stop....
• A notice from agent-vm (for example about Local Network access) is shown while the job is at the step it belongs to, and stays in the log after that.
• When a job the app was watching ends, the app says so: a short message when it did what was asked, agent-vm's own words when it failed.
• Builds and downloads that ended while the app was closed are reported at the next launch.

Agent keys

Settings > Agent Keys... lists the agents avm can run and the API keys each can use, and says which are stored. A key you type goes straight to agent-vm, which stores it; the app keeps no copy and never writes it to a file.

Full Disk Access

• On your Mac, AgentVM neither needs nor asks for Full Disk Access. The agent runs in a box and sees only the project folder you share.
• Inside an image, it is optional. Set Up... on an image opens a guide that grants it to agent-vm-guest, the program that starts everything in a box. That grant covers the box's own disk, which holds nothing of yours. Without it boxes still work: only a program that opens the box account's Desktop, Documents or Downloads waits for permission macOS pops up on the box's screen.

Links

Other apps and scripts can open AgentVM.app at a place. A link only shows; it never changes a box or an image.

open agentvm://status          # the main window
open agentvm://box/<name>      # with that box selected
open agentvm://image/<name>    # with that image selected

Good to know

• Local Network access. During the first build of an image, macOS asks whether AgentVM may find devices on local networks. Allow it: that is how the build reaches the new virtual machine on this Mac. The app does not look for other devices on your network. If it was declined, turn AgentVM on in System Settings > Privacy & Security > Local Network; a build that is waiting goes on by itself.
• Disk space. A restore file is about 27 GB. An image's disk is a sparse file, which takes only what is written to it, and a box shares what it did not change with its image.
• How many at once. macOS runs a limited number of macOS virtual machines at a time, and a build needs one. Settings shows the count.
• One agent-vm. Terminal, Cadabra and this app all run the copy in ~/.local/bin.

Requirements and installing

• A Mac with Apple silicon and macOS 27 or later. The app does not open anywhere else.
• agent-vm 0.6.14 or later. The app offers to install or update it.

Open AgentVM_1.0.zip and move AgentVM.app to the Applications folder.

License

Apache License 2.0, as agent-vm.