Quickstart

Provision a microVM, tail its lifecycle, and tear it down

This walks through the full lifecycle of an environment using the TypeScript SDK: create one, wait for it to come up, and destroy it.

Full example

import { FuseClient } from "@folsom/fuse";

const client = new FuseClient({
  baseUrl: "https://orchestrator.example.com",
  token: process.env.FUSE_TOKEN,
});

const env = await client.environments.create({
  task_id: "task-1",
  spec: { cpus: 1, ram_mb: 512 },
});
console.log("created:", env.id, env.state);

const ac = new AbortController();
const stream = await client.environments.events(env.id, { signal: ac.signal });
for await (const event of stream) {
  console.log("state:", event.state);
  if (event.state === "running") ac.abort();
}

await client.environments.destroy(env.id);
console.log("destroyed:", env.id);

What each step does

create provisions a microVM from a spec (CPUs, RAM, storage, and optionally GPU). It blocks server-side until the environment is running or provisioning fails; the returned EnvironmentInfo reflects whatever state the environment reached. Note the wire field names: task_id and ram_mb, not taskId/ramMb, request and response bodies are snake_case throughout.

events returns a promise that resolves to an AsyncIterable<Event>. It rejects immediately on a connect-time error (for example not_found); once connected, the stream yields the current state first, then each transition, and ends on its own after a terminal-state event (destroyed/failed). Because create has already blocked until the environment is running, the stream above yields that running snapshot and would then sit on keepalives until the environment dies, the AbortController is what ends it. There is no built-in timeout on the stream itself, and an abort is treated as a clean end rather than an error, so the loop exits without throwing.

destroy tears the environment down. It is not idempotent: destroying an already-gone environment throws a FuseApiError with code === "not_found", so guard repeat calls with isNotFound(err) rather than calling blind.

Next steps

• Environments covers every method on the environments service, including drain, fork, and rotate-token.
• Errors covers how to branch on the server’s error codes with the is* helpers instead of comparing strings.