microVMs

Create, inspect, run commands in, copy files to and stop microVMs from the terminal with gigadrive microvms.

gigadrive microvms manages microVMs from your terminal. Use it to try an image, open a shell in a running microVM to debug what an agent or a job left behind, or clean up microVMs you no longer need. gigadrive vm is an alias that takes the same subcommands.

Command	What it does
`gigadrive microvms create`	Create a microVM and wait until it runs
`gigadrive microvms ls`	List running microVMs, or all of them with `--all`
`gigadrive microvms get`	Print one microVM, including its preview URLs
`gigadrive microvms metrics`	Show a microVM's CPU, memory and disk use
`gigadrive microvms exec`	Run a command in a microVM and exit with its exit code
`gigadrive microvms shell`	Open an interactive shell in a microVM
`gigadrive microvms cp`	Copy files or directories between your machine and a microVM
`gigadrive microvms stop`	Stop one or more microVMs
`gigadrive microvms rm`	Delete one or more microVMs, stopping them first
`gigadrive microvms extend`	Set how long a microVM keeps running, counted from now
`gigadrive microvms images ls`	List the built-in images and the application's custom images
`gigadrive microvms images create`	Build a custom image from a registry image or a Dockerfile
`gigadrive microvms images rm`	Delete a custom image
`gigadrive microvms webhooks`	Manage webhooks for lifecycle events

Commands that create or list microVMs or images work on the linked application unless you pass --app. See Project linking. The Command reference lists every flag.

Create a microVM and open a shell

gigadrive microvms create with no flags starts the default node22 image with 1 vCPU, 2 GiB of memory and a five-minute timeout, and prints the new microVM with its ID:

gigadrive microvms create

Pass that ID to shell to get an interactive terminal inside it. The shell runs as the image's user, and closing it leaves the microVM running:

gigadrive microvms shell 0199a7c4-5b1e-7c3d-9f20-333333333333

shell needs an interactive terminal. In scripts, use exec instead.

Run a command

Put the command after --. exec streams its output to your terminal and exits with its exit code, or with 128 plus the signal number when a signal ended it. A single quoted argument runs through /bin/sh -c, so pipes work:

gigadrive microvms exec 0199a7c4-5b1e-7c3d-9f20-333333333333 -- npm test
gigadrive microvms exec 0199a7c4-5b1e-7c3d-9f20-333333333333 -- 'ls -la | wc -l'

Add --interactive to forward your terminal's input to the command. Pressing Ctrl-C sends SIGINT to the command.

Copy files

One side of cp is a local path and the other is vm:<id>:<path>. A directory is copied with everything in it:

gigadrive microvms cp ./app vm:0199a7c4-5b1e-7c3d-9f20-333333333333:/srv/app
gigadrive microvms cp vm:0199a7c4-5b1e-7c3d-9f20-333333333333:/srv/app/dist ./dist

Clean up

List what is running, then stop or delete what you no longer need. A running microVM is billed for its memory until it stops, so stop the ones you are done with rather than waiting for their timeout.

gigadrive microvms ls
gigadrive microvms stop 0199a7c4-5b1e-7c3d-9f20-333333333333

The commands need a sign-in or credential with the network:microvms:* scopes, and the images commands need the network:microvm_images:* scopes; see Scopes. Limits and pricing lists the sizes and timeouts you can choose.