Skip to content
docs.microagent.sh

Coming from Docker

Last updated: 2026-08-12

If you think in Docker commands, most of them carry over. The big difference: each “container” is a real microVM with its own kernel, and the named persistent unit is called a workspace. This page maps the commands first, then covers what is intentionally different.

Command map

Section titled “Command map”
Docker microagent Notes
docker run --rm IMAGE CMD microagent run IMAGE CMD One-shot: boots a microVM, runs the command, removes scratch state. Disposable is the default; pass --keep to keep state.
docker run -d --name web IMAGE microagent create --name web --image IMAGE, then microagent start web A workspace persists between starts. Use --service-command for a long-running process.
docker ps microagent ps Lists running workspaces. Use microagent list or microagent ls for saved workspace inventory.
docker exec web CMD microagent exec web -- CMD Structured result with exit code, stdout, and stderr. Note the -- before the command.
docker exec -it web bash microagent connect web Opens the workspace console.
docker stop web microagent halt web Graceful shutdown; stop also works as a pure alias of halt. If the VM doesn’t shut down cleanly within the fixed graceful window, follow up with microagent kill. See halt, not stop.
docker rm web microagent delete web Prompts before deleting; if the workspace is running it offers to stop it first. --force kills and deletes.
docker cp app.py web:/srv/ microagent cp app.py web:/srv/ Same shape, but works on a stopped workspace: files move through the disk image, not a running daemon.
docker logs web microagent logs web Captured serial console output. -f follows.
docker images microagent image list Lists local image records.
docker commit web REF microagent commit web REF Snapshots a stopped workspace’s rootfs into an OCI image.
docker network inspect web microagent network web Inspect a workspace’s network. microagent has two modes: user (default outbound NAT plus published ports) and isolated.
docker volume create/ls/inspect/rm microagent volume create/list/status/delete Named volumes are managed ext4 disks. Attach with -v data:/work.

The familiar flags work where they map cleanly to microVM behavior: -e (guest environment variable), -p (publish a TCP port), --name, and --rm. The -v flag is deliberately narrow: it accepts named volumes, tar bundles, and ext4 disk images, not host directories. Unsupported features such as --privileged, namespace flags, and host bind mounts fail with targeted guidance instead of being silently translated.

What’s intentionally different

Section titled “What’s intentionally different”

No bind mounts

Section titled “No bind mounts”

There is no -v /host/dir:/guest/dir. A volume is a managed ext4 disk (or a tar bundle built into one), and everything the guest reads or writes is a block device. The microVM boundary means the guest never shares a live host filesystem. To move a directory in, package it as a tar bundle; to move files out, use microagent cp or declare --output artifacts. See Storage.

No –privileged

Section titled “No –privileged”

The guest already has its own kernel and full root inside the microVM, so there is no privileged mode to escalate to. Host access stays on the host.

No build command

Section titled “No build command”

microagent does not build images. Build with the tooling you use today (Docker, Buildah, your CI) and point microagent run at the result; it consumes standard OCI images. To capture changes a workspace made to its rootfs, microagent commit snapshots a stopped workspace back into an OCI image.

Halt, not stop

Section titled “Halt, not stop”

Docker has stop and kill. microagent’s canonical graceful verb is halt; stop is a pure alias of halt, so the docker stop habit keeps working unchanged:

  • halt (alias stop) - clean disk-preserving shutdown. Guest PID 1 sends the image’s OCI StopSignal to the workload, then powers off. The host gives that sequence about 15 seconds; the VM process exits, the disk stays, and start boots the same disk back up.
  • kill - hard terminate, for when the guest doesn’t exit within that window. halt never escalates to kill on its own.

Both leave the disk in place. halt is the deliberate “park it and start it later” verb; kill is for making an unresponsive VM process go away.

delete prompts before deleting; if the workspace is running it offers to halt it first. --force kills and deletes. The glossary has the full lifecycle vocabulary, including pause/resume and quarantine.

Section titled “Related”