Quickstart

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

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

Full example

package main

import (
	"context"
	"log"

	fuse "github.com/folsomintel/fuse/sdks/go"
)

func main() {
	ctx := context.Background()

	client, err := fuse.New("https://orchestrator.example.com", "token")
	if err != nil {
		log.Fatal(err)
	}

	env, err := client.Environments.Create(ctx, fuse.CreateRequest{
		TaskID: "task-1",
		Spec: fuse.Spec{
			CPUs:  1,
			RamMB: 512,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("created:", env.ID, env.State)

	events, err := client.Environments.Events(ctx, env.ID)
	if err != nil {
		log.Fatal(err)
	}
	for ev := range events {
		if ev.Err != nil {
			log.Fatal(ev.Err)
		}
		log.Println("state:", ev.State)
		if fuse.IsSettledState(ev.State) {
			break
		}
	}

	if err := client.Environments.Destroy(ctx, env.ID); err != nil {
		log.Fatal(err)
	}
	log.Println("destroyed:", env.ID)
}

Create provisions a microVM from a Spec (CPUs, RAM, storage, and optionally GPU). Create blocks server-side until the environment is running, and returns an error if provisioning fails. There is no success path that hands back an *EnvironmentInfo in failed state, so don’t branch on env.State == fuse.StateFailed after a nil-error Create, that branch can never be taken.

Events opens the SSE event stream for that environment and returns a <-chan Event. The stream delivers the current state immediately on connect, then one event per transition. It closes on its own after a terminal state (destroyed or failed), or after a final Event with Err set if the stream itself failed. There is no built-in timeout: cancel ctx to stop it early.

Because Create has already returned by this point, the first event is a snapshot of the current state (running) and nothing transitions after it until something destroys the environment. Break on fuse.IsSettledState, as above, which covers running plus both terminal states. Do not loop on fuse.IsTerminalState: it is only ever true for destroyed or failed, so a healthy environment never satisfies it and the loop blocks forever. IsTerminalState is for callers that genuinely want to watch an environment until it goes away.

Destroy tears the environment down. It is idempotent: destroying an already-gone environment returns a not_found *APIError, not a panic or a different error shape.

Next steps

Environments covers every method on EnvironmentsService, including drain, fork, and rotate-token.
Errors covers how to branch on the server’s error codes instead of comparing strings.

Quickstart

Full example

What each step does

Next steps