Quickstart

  1. Prerequisites
  2. First program
  3. Next

Prerequisites

  • Apple Silicon Mac (kern.hv_support = 1)
  • Go 1.25+
  • Docker once, to pack the golden root filesystem (make image)
  • Homebrew libkrun + libkrunfw
brew tap libkrun/krun
brew trust libkrun/krun
brew install libkrun libkrunfw

From a clone of ABox:

make build
make image          # first time only; Docker
export PATH="$PWD/bin:$PATH"

Put a provider key in the host (the SDK loads ~/.abox/credentials.env the same way the CLI does):

# in the ABox TUI
/provider

or write ~/.abox/credentials.env (mode 0600) with XAI_API_KEY=… (or OpenAI / Anthropic).

First program

One import: github.com/AdminTurnedDevOps/ABox/pkg/abox. Work from any git repo (the SDK snapshots that tree into the guest).

go get github.com/AdminTurnedDevOps/ABox@latest

Copy this into main.go:

package main

import (
	"context"
	"fmt"
	"os"
	"os/signal"

	"github.com/AdminTurnedDevOps/ABox/pkg/abox"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	sess, err := abox.Open(ctx, abox.Options{})
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	defer sess.Close()

	fmt.Println("session", sess.ID(), "protocol", sess.Capabilities().Protocol)
	_, err = sess.Turn(ctx, "Say hello in one sentence.", func(ev abox.Event) {
		if ev.Kind == "text" {
			fmt.Print(ev.Text)
		}
	})
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	fmt.Println()
}

export PATH="/path/to/abox-vmm-dir:$PATH"   # from the GitHub release archive
go run .

You should see protocol 2 and a streamed sentence. Close() stops the VM.

abox-vmm must be on PATH, or set Options.VMMPath. More methods: Examples.

Next