Quickstart

This walkthrough creates a microVM, runs a command, writes a web page into it, serves the page on a public preview URL and stops the microVM. The whole run costs a fraction of a cent.

Before you start

• An application to own the microVM.
• A credential with the network:microvms:write and network:microvms:exec scopes. Scopes lists what each one allows.
• For TypeScript, @gigadrive/sdk installed and configured as described in SDK authentication. The SDK takes the application from GIGADRIVE_APPLICATION_ID.
• For REST, an access token in GIGADRIVE_TOKEN. Authentication shows how to mint one.

Run it

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

// 1. Create a microVM with port 3000 exposed. It is running when create returns.
const vm = await MicroVM.create({ image: 'node22', ports: [3000] });

try {
  // 2. Run a command and wait for it to finish.
  const version = await vm.run('node', ['--version']);
  console.log(version.stdout);

  // 3. Write a file. Missing parent directories are created.
  await vm.files.write('/tmp/site/index.html', '<h1>Hello from a microVM</h1>');

  // 4. Start a web server in the background and wait until it answers.
  await vm.spawn('npx', ['--yes', 'serve', '--listen', '3000', '/tmp/site']);
  const url = await vm.waitForPort(3000);

  // 5. Open this URL in a browser.
  console.log(url);
} finally {
  // 6. Stop the microVM. It would also stop by itself when its five-minute timeout ends.
  await vm.stop();
}

The server in this example listens on every interface, which is what makes the preview URL reach it. A server that listens only on localhost or 127.0.0.1 is not reachable from outside the microVM. Ports and previews covers this and WebSockets.

Next steps

• Commands: stream output, send input, use a terminal, and set timeouts.
• Files: upload a project, read results back and list directories.
• Images: start from Python, Bun, Debian or Ubuntu, or bring your own image.
• Limits and pricing: what a microVM can be sized to, and what it costs.