Named workspaces

A workspace is a named, persistent VM record. Unlike microagent run, the disk and state stick around between starts, so you can stop and resume an agent’s environment.

Create

microagent create \
  --name research \
  --image docker.io/library/ubuntu:24.04 \
  --size-mib 2048 \
  --memory 1024 \
  --cpus 2 \
  --setup "mkdir -p /workspace" \
  --setup "echo ready > /workspace/status"

The name can also be positional:

microagent create research --image docker.io/library/ubuntu:24.04

Microagent builds the rootfs once and records workspace metadata in the state directory. If the default kernel is missing, create installs it first.

Start

microagent start research

Connect (Apple VF)

microagent connect research

For scripts, send one line and capture new console output:

microagent connect research --send "cat /workspace/status"

connect is supported on Apple VF only. For Firecracker workspaces, use logs for serial output.

Inspect

microagent ps                       # list all workspaces
microagent status --name research   # full state for one
microagent logs research            # boot/serial output

Stop and delete

microagent stop research
microagent delete research

For Firecracker, delete refuses to remove state while the recorded VM process is still running. Use stop or kill first.

Attach disks

Attach an existing ext4 disk:

microagent create \
  --name research \
  --image docker.io/library/ubuntu:24.04 \
  --disk workspace=/tmp/workspace.ext4:/workspace:rw

Build a disk from a tar bundle and mount it read-only:

microagent create \
  --name research \
  --image docker.io/library/ubuntu:24.04 \
  --bundle config=/tmp/config.tar:/config:ro