Skip to content

AgentVM app 1.0

Choose a tag to compare

View all tags
@abra-code abra-code released this 05 Oct 21:44
· 25 commits to main since this release
v1.0
84c4f7d

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.

Assets 3
Loading