Go library

Want the smallest useful program first? See the library quickstart. This page is the package reference.

Use it as a generic microVM toolkit

The library doesn’t require agent semantics. The same packages back the CLI’s agent-flavored workflows and any program that just wants microVMs: build a rootfs from an OCI image, boot a VM, run a command, tear it down. The high-level pkg/workspace API treats every workspace as a workload-role identity by default — you get caller-visible identity for free without writing agent-aware code, and you can drop down to pkg/vmkit when you need a different role or a custom supervisor request.

Exported packages

microagent has these exported Go packages today:

Package	Purpose
pkg/vmkit	supervisor request/response types, validation, and executable supervisor client
pkg/workspace	workspace lifecycle API, options, defaults, request construction, backend supervisor selection, and backend-neutral helpers
pkg/kernel	kernel default manifest, install, verify, and support checks
pkg/imagecache	reusable rootfs image cache indexing, pull, tag, remove, and prune
pkg/diagnostics	backend host diagnostics and support summaries
pkg/rootfs	OCI image and tar bundle conversion into ext4 disks
pkg/supervisors/firecracker	Linux Firecracker supervisor implementation

The CLI is an adapter over these packages. Go callers should use the library directly for workspace lifecycle operations instead of shelling out to microagent.

Supervisor types

Use pkg/vmkit when you need the shared request/response schema or want to call an executable supervisor.

package main

import (
  "context"
  "fmt"

  "github.com/geoffbelknap/microagent/pkg/vmkit"
)

func main() {
  resp, err := vmkit.ExecutableSupervisor{
    Path: "microagent-firecracker-supervisor",
  }.Do(context.Background(), vmkit.Request{Command: "host"})
  if err != nil {
    panic(err)
  }
  fmt.Println(resp.Backend, resp.OK)
}

On Linux, Go callers can also use github.com/geoffbelknap/microagent/pkg/supervisors/firecracker directly:

resp, err := firecrackersupervisor.Supervisor{}.Do(ctx, req)

For backend-independent code, depend on the interface:

func inspect(ctx context.Context, supervisor vmkit.Supervisor, req vmkit.Request) (vmkit.Response, error) {
  req.Command = "inspect"
  return supervisor.Do(ctx, req)
}

Rootfs builder

Use pkg/rootfs when your program needs to build a VM rootfs from an OCI image without shelling out to microagent rootfs.

package main

import (
  "context"

  "github.com/geoffbelknap/microagent/pkg/rootfs"
)

func main() {
  _, err := rootfs.NewBuilder().Build(context.Background(), rootfs.BuildRequest{
    ImageRef:   "docker.io/library/ubuntu:24.04",
    Platform:   rootfs.Platform{OS: "linux", Architecture: "amd64"},
    OutputPath: "/tmp/rootfs.ext4",
    StateDir:   "/tmp/microagent-build",
    SizeMiB:    2048,
  })
  if err != nil {
    panic(err)
  }
}

Workspace API

Use pkg/workspace when your program wants to create, run, start, inspect, and control named workspaces without parsing CLI flags.

workspace.DefaultOptions() picks the host backend (Firecracker on Linux, Apple Virtualization.framework on macOS), guest architecture, default kernel path, and default state directory. You override only what your program needs.

package main

import (
  "context"
  "fmt"

  "github.com/geoffbelknap/microagent/pkg/workspace"
)

func main() {
  opts := workspace.DefaultOptions()
  opts.Name = "demo-vm"
  opts.ImageRef = "docker.io/library/ubuntu:24.04"
  opts.ExecCommand = "uname -a"

  result, err := workspace.Run(context.Background(), opts)
  if err != nil {
    panic(err)
  }
  if result.Result != nil {
    fmt.Print(result.Result.Stdout)
  }
}

Result.Result is a *GuestResult with Stdout, Stderr, and ExitCode captured from the guest. Result.Response carries the supervisor’s structured response (state, identity, verification).

For non-defaults — backend override, custom kernel, sized memory/CPUs, networking — set the matching Options fields before calling Run. The lifecycle API:

Function	Purpose
workspace.Create	Build and prepare a named workspace rootfs and manifest
workspace.Run	Build, run, collect result state, and optionally clean up
workspace.Start	Start an existing named workspace from its manifest
workspace.Inspect	Ask the backend supervisor for current runtime state
workspace.Status	Read enriched local workspace status from state files
workspace.ResultStatus	Read status plus guest result output
workspace.ArtifactsFor	Read declared ingress and egress artifacts
workspace.GetArtifact	Copy a declared output artifact from a stopped workspace
workspace.Copy	Copy files between the host and a stopped workspace disk
workspace.Clone	Clone a stopped/prepared workspace
workspace.ReadLogs	Read a workspace serial log
workspace.Network	Read configured and runtime network state
workspace.List	List named workspaces from local state
workspace.Control	Halt, quarantine, stop, kill, or delete a workspace
workspace.Supervise	Run the optional restart-policy loop for a workspace
workspace.ReadManifest / workspace.WriteManifest	Manage workspace manifests directly

Kernel API

Use pkg/kernel when your program wants microagent to manage backend kernel assets directly.

result, err := kernel.Install(ctx, kernel.InstallOptions{
  Backend:      vmkit.BackendFirecracker,
  Architecture: "amd64",
})
if err != nil {
  panic(err)
}

verified, err := kernel.Verify(kernel.VerifyOptions{
  Path:   result.Path,
  SHA256: result.SHA256,
})
if err != nil {
  panic(err)
}
_ = verified

Image cache API

Use pkg/imagecache when an orchestrator wants reusable rootfs baselines.

record, err := imagecache.Pull(ctx, imagecache.PullOptions{
  StateDir:     "/home/me/.microagent",
  ImageRef:     "docker.io/library/ubuntu@sha256:...",
  Architecture: "amd64",
})
if err != nil {
  panic(err)
}
_ = record

Diagnostics API

Use pkg/diagnostics for host preflight checks.

resp, err := diagnostics.Check(ctx, diagnostics.Options{
  Backend: vmkit.BackendFirecracker,
  Arch:    "amd64",
})
if err != nil {
  // resp still contains structured support details when available.
}
_ = resp

The CLI contains presentation, flag parsing, and terminal-oriented behavior. microVM orchestration and management capabilities are exposed through the Go packages.

CLI ↔ library mapping

If you already know the CLI, this is the lookup for the equivalent library call:

CLI command	Library call
microagent run	workspace.Run
microagent create	workspace.Create
microagent start	workspace.Start
microagent status	workspace.Status (local) / workspace.Inspect (live, via supervisor)
microagent result	workspace.ResultStatus
microagent ps	workspace.List
microagent halt / quarantine / stop / kill / delete	workspace.Control (one function, action picked via options)
microagent supervise	workspace.Supervise
microagent connect	No direct library equivalent — interactive console is CLI-only. Use workspace.ReadLogs for captured serial output.
microagent logs	workspace.ReadLogs
microagent cp	workspace.Copy
microagent clone	workspace.Clone
microagent artifacts / artifacts get	workspace.ArtifactsFor / workspace.GetArtifact
microagent network	workspace.Network
microagent doctor / host	diagnostics.Check
microagent contract	vmkit.Contract
microagent kernel install / verify	kernel.Install / kernel.Verify
microagent rootfs build	rootfs.Builder.Build
microagent images pull / list / tag / rm / prune	imagecache.Pull / List / Tag / Remove / Prune
microagent.yaml (spec parsing)	workspace.ReadManifest / WriteManifest

The library calls take options structs and return typed responses. The CLI is a thin shell over them — anything the CLI does, your program can do too without shelling out.