Images
A MicroVM runs from an image built in your AWS account. The image decides what's installed, and the MicroVM's size and architecture. Settings → Images lists the images in a profile and region, builds new ones and updates them.
The list
The tab is for the profile Settings shows (the switcher at the top). Choose the region from the profile's listed regions.
- Default image for new workspaces is kept for each profile and region: the tab shows, and sets, the default image of the region it is showing. A new workspace starts in the profile's default region, on that region's default image; change the region in the workspace editor and the image becomes that region's default.
- Starter image says whether the starter image is built there, with Build Starter Image… or Update Starter Image…. Its sheet asks only for the size; New Image… has every value.
- Your images shows each image's version, architecture, size and price, and the workspaces that use it. Refresh lists them again. An image MicroVM Studio built says Up to date, or A newer recipe is available: choose Update…. Others say Not built by this app. One built from your own Dockerfile says so.
- AWS base images are listed for reference: images are built on them, and they can't be run themselves.
New Image…
New Image… opens a sheet with two views, Quick start and Advanced, the way the workspace editor does.
Quick start images
A name, a region and a size. Everything else takes the default: ARM64, git, GitHub CLI, tmux, Node.js 22, Python 3, the AWS CLI, Claude Code, Codex and the EFS tools, all OS capabilities, and the mount at launch. It keeps the EFS tools and the mount, so a quick start image still works if you turn on persistent storage later.
- Name: letters, digits, hyphens and underscores, up to 64.
- Region: one of the profile's listed regions. The first build in a region makes its S3 bucket.
- Size: see below.
Advanced images
Every value, with everything it offers shown:
- Base image version: the latest by default, or a version of AWS's base image in that region.
- Architecture: ARM64, or x86-64 where the base image version supports it. One it doesn't is greyed, with why.
- Size: all five, see below.
- Packages: git, GitHub CLI, tmux, Node.js 22, Python 3, AWS CLI, Claude Code, Codex and EFS tools, each with what it adds. A package another one needs stays ticked while that one is: Codex needs Node.js.
- Extra setup: shell lines, run as root while the image is built, after the packages are installed.
- All OS capabilities and Mount /workspace at launch: see below.
- Dockerfile: see below.
- Use it as the default image for new workspaces.
Before Build, the sheet lists what it creates, with their tags: the S3 bucket and the recipe in it, the IAM role for the build and its policies, and the image. AWS writes the build's log to CloudWatch. Closing the sheet doesn't stop the build.
The Dockerfile
The last section of Advanced shows the Dockerfile the build uploads. While you only use the choices above it, the file is written from them and changes as they do. Type in it and it becomes yours: the build uploads exactly your text, and the choices that write it (packages, extra setup, mount at launch) lock. Reset to Generated goes back to the file the choices write.
The file must not be empty, must start with FROM (comments and blank lines may come first), and must fit the size the build upload allows; the sheet says in plain words what's wrong. What you control and what the build call keeps lists the rules:
- The base image comes from the build settings, not your
FROMline; yourFROMline starts your file and has to be a public image with a build for the architecture you chose. - Everything after
FROMis yours: packages, users, tools, settings,ENTRYPOINTandCMD. - The upload holds only the Dockerfile, so
COPYandADDhave no files next to it. UseRUNto download or write files. - Architecture, size and OS capabilities are build settings, not part of the file. Storage also needs amazon-efs-utils installed by your file.
- Mount at launch needs the app's listener in your file. The generated file downloads it while the image builds, from MicroVM Studio's site, and checks it against a sha256 the app pins, so a file that changed fails the build. MicroVM Studio never adds it to a file you wrote: keep the generated listener lines (the
RUNthat downloads it and theCMDthat starts it), or turn Mount at launch off. A Dockerfile saved by an older version, with the listener written into it as one long base64 line, still works.
Sizes
An image's size sets the vCPUs and memory of every MicroVM made from it, and so what it costs: CPU follows memory. These are the five sizes, with their compute price an hour while running in us-east-1; the sheet shows the price in the image's own region.
- 1 vCPU · 2 GB (≈ $0.13/h)
- 2 vCPU · 4 GB (≈ $0.25/h)
- 4 vCPU · 8 GB (≈ $0.50/h)
- 8 vCPU · 16 GB (≈ $1.01/h)
- 16 vCPU · 32 GB (≈ $2.02/h)
The starter image is 1 vCPU · 2 GB unless you choose another. Your AWS account's memory quota counts each MicroVM's size, per architecture: see Memory quota reached in Troubleshooting.
An image with Claude Code or Codex keeps them in its MicroVMs' memory, because a MicroVM reads its disk slowly the first time: they start in a second or two instead of 12 to 35. That takes about 330 MB of the MicroVM's memory for each, which nothing else can use. To give it back, add : > /etc/microvm-studio/keep-in-memory to the image's extra setup.
Persistent /workspace in an image
- All OS capabilities: root in its MicroVMs gets every Linux capability, which mounting a persistent
/workspaceneeds. With it on, EFS tools are always installed. A workspace set to Run as root then has full control of its MicroVM. Without it, workspaces using the image can't keep/workspaceon a file system. - Mount /workspace at launch: a small listener in the image (its lifecycle hooks) mounts
/workspaceas each MicroVM starts, so it's ready when you connect. Without it,/workspaceis mounted when the terminal connects.
Both are on in the starter image and in Quick start images. The row of an image MicroVM Studio built says when one is missing.
Update…
Update… opens the recipe of an image MicroVM Studio built. Change it, then Update builds a new version under the same name and region; a new name or region would make another image. If nothing changed, the image is already up to date. AWS keeps only a hash of the extra setup, so if this Mac doesn't have it, type it again, or leave it empty to build without it.
Delete…
Delete… deletes the image and all its versions in its region. MicroVMs already running from it keep running, and it can't be undone. An image a saved workspace uses can't be deleted: choose another image for the workspace first. Deleting the default image for new workspaces leaves no default. AWS base images can't be deleted.