Workspaces
A workspace says how to start a MicroVM and what to put in it. The editor has two views, chosen at the top: Quick start and Advanced. They are two views of the same workspace.
Quick start
Quick start asks for the name, the AWS profile (the one Settings is showing), the image, the repos and GitHub access, and how Claude Code and Codex sign in. Everything else takes a default, which the note under the fields spells out: internet egress, no persistent storage, suspend after 5 minutes idle, terminate after 8 hours suspended, up to 8 hours in total, and resume on connect.
Quick start never changes a value it doesn't show. A workspace that has values only Advanced shows opens in Advanced, and in Quick start a note names them.
Advanced
Advanced shows everything:
- General: the name, AWS profile, region and image. The Region menu offers the regions listed for the workspace's own profile. The Image menu shows each image's architecture and size. Under it, the chosen image's region, and whether it supports a persistent
/workspaceand mounts it while the MicroVM starts. Changing the AWS profile keeps the region if the new profile lists it, else moves to that profile's default region; the image becomes that region's default image, and the AWS role is cleared, because a role belongs to the old profile's account. - Time limits: Max duration, Suspend when idle, Terminate after suspended for and Resume on connect. Each time is a number with Minutes or Hours, and a pop-up of shortcuts, so any whole value works: the max duration from 1 minute to 8 hours, and the other two from 1 minute up to the max duration. Suspend when idle can also be Off. After the max duration the MicroVM is terminated, even if you're still working in it. A value outside the limits is explained beside its field.
- Behaviour: Keep the session when you disconnect (tmux) and Run as root. See Terminals and Sessions.
- GitHub: access, and the repos to clone. The Access menu can also sign in to GitHub, or add another account. See GitHub.
- AWS role: the role the MicroVM runs as.
- Network connector: where the MicroVM leaves through. Internet (default) is AWS's own egress and needs no VPC. Or choose one of the profile's VPC network connectors in the workspace's region: it reaches that VPC, and needs a NAT gateway there for internet. With persistent storage the choice is the file system's own connector, shown and greyed. See Network Connectors.
- Storage: an optional persistent
/workspace. - Claude Code: how Claude Code signs in.
- Codex: how Codex signs in. See Codex.
- Secrets: each goes into an environment variable, or into a file only you can read. Their values stay in this Mac's Keychain, never in the workspace; manage them in Settings → Secrets.
- Files to copy: small files from this Mac, such as
~/.gitconfig. - Setup commands: one per line. They run after the repos are cloned, and once they succeed they don't run again in that MicroVM.
- Start command: runs when the session starts, for example
claudeorcodex. Leave it empty for a plain shell.
Launching
Press the ▶ button on the workspace's row in the sidebar or Launch on its page, or choose Launch from its right-click menu or the MicroVM menu. The MicroVM starts, then setup runs and its terminal connects.
If it takes longer than 90 seconds to start, that isn't an error. The sidebar and the terminal say it's taking longer than usual, and MicroVM Studio keeps checking every 5 seconds until the MicroVM runs or stops. This can happen when it mounts storage or the image is large.
If the workspace already has a MicroVM that's running, starting or suspended, MicroVM Studio asks first. Open one of those, named by when it started and its state (a suspended one is resumed), choose Start a New MicroVM, or Cancel. With more than two, it offers the newest; the others are in the sidebar.
The sidebar
Workspaces are grouped under their profile's badge. Each lists its MicroVMs under it, newest first. Other MicroVMs holds the ones no saved workspace launched. Show: at the bottom chooses between Active only, Active and recently terminated (in the last 10 minutes) and Active and all terminated. The list refreshes every minute; ⌘R refreshes it now.
The MicroVM menu
The MicroVM menu acts on what's selected in the sidebar: Launch and Edit Workspace… for a workspace (or a MicroVM's workspace), and Connect, Disconnect, Suspend, Resume, Terminate…, Upload…, Download… and History for a MicroVM. An item that doesn't apply is dimmed. Refresh and Focus Sidebar are in the View menu, with Show Sidebar and Hide Sidebar, and New Workspace… (⌘N) is in the File menu.
Editing
Press the pencil button on the workspace's row in the sidebar, beside ▶; or press Edit… on its page, or choose it from its right-click menu. Cancel asks before it discards changes. The image, role, storage, network, max duration, and when the MicroVM suspends and is terminated, are set when a MicroVM launches, so changes to them apply to the next one. Credentials and repos are brought up to date each time a MicroVM from the workspace connects. Files to copy and setup commands run only once per MicroVM.
Deleting
Choose Delete… from the workspace's right-click menu, or Delete Workspace… in the editor. Only the saved workspace goes. Its MicroVMs keep running and move to Other MicroVMs, where they connect as plain shells. Its secrets stay saved and its AWS role stays in your account. With a persistent /workspace, its folder and files stay on the file system.