microVMs

A microVM is an isolated Linux machine that you create on demand, run commands in, read and write files on, and reach over public preview URLs. Use one when code has to run somewhere that is not your Function: code an AI agent wrote, a user's untrusted script, a preview of a branch, or a build or test job.

When to use a microVM

• AI agents that execute code. Give each agent session its own machine, let it install packages and run what it wrote, and read the results back.
• Untrusted code. Each microVM is isolated from every other microVM and from your applications, and you can turn off its internet access.
• Previews. Start a dev server for a branch or a generated app and share its preview URL.
• Build and test jobs. Clone a repository, install dependencies and run the test suite, then throw the machine away.

A microVM is not a place to serve production traffic. It stops at the end of its timeout, keeps nothing after it stops, and has no autoscaling. Deploy long-lived services as Functions instead.

Create one and run a command

This example creates a microVM from the built-in node22 image, runs a command in it and stops it.

import { MicroVM } from '@gigadrive/sdk';

await using vm = await MicroVM.create({ image: 'node22' });

const result = await vm.run('node', ['-e', 'console.log(1 + 1)']);

console.log(result.exitCode, result.stdout); // 0 "2\n"

Every microVM belongs to one application, and access follows that application. Pass applicationId when you create one; a credential bound to a single application, such as an application API key, can omit it. The Quickstart goes on to write files and open a preview URL.

Lifecycle

A microVM moves through these states. stopped and failed are final: a stopped microVM cannot be started again, so create a new one.

Each microVM has a timeout, five minutes unless you set one, after which it stops on its own. You can extend it while it runs, up to your plan's maximum lifetime. stopReason on a stopped microVM tells you what ended it, for example timeout, user or billing_suspended. Rarely, platform maintenance stops a running microVM with maintenance, so treat microVMs as disposable and keep anything you need outside them.

Stopping a microVM that has already stopped succeeds and changes nothing. Deleting one stops it first if it is still running, then removes it from lists.

A stopped or failed microVM stays visible in lists for 30 days, then disappears.

Pause and resume

Pause a running microVM to keep its memory, running processes and files while it accrues no CPU or memory, and resume it later where it left off. Its timeout stops counting while it is paused. To start new microVMs from a prepared state instead, take a snapshot and create microVMs from it. Pause, resume and snapshots covers both.

curl -X POST https://api.gigadrive.network/microvms/0199a7c4-5b1e-7c3d-9f20-333333333333/pause \
  -H "Authorization: Bearer $GIGADRIVE_TOKEN"

In the console

Open an application in the console and select microVMs in the sidebar. The page lists the application's microVMs with their status, image, size and preview URLs, and Create microVM starts a new one. On a microVM's page you can extend or stop it, run commands, browse, view and upload files, and open a terminal. The Images tab lists the built-in images and builds custom ones.