ABox Go SDK

Build an agent without putting the model loop on the host.

The agent loop and tools run in abox-guest inside a libkrun microVM. Your process is the supervisor: open a session, stream events, approve shell, cancel a turn, close the VM. Provider HTTPS and MCP HTTPS stay on the host. The guest never sees a credential, base URL, or MCP endpoint.

If you want to…	Use
Drive the agent from your own Go program	This SDK (pkg/abox)
Chat in a terminal	CLI and TUI (abox)
Store keys	Credentials
Attach remote tools	MCP
Gate model-authored shell	Approvals
Boot the VM and list files, no model	abox --probe-vm or Session.ListFiles

sess, err := abox.Open(ctx, abox.Options{})
if err != nil { log.Fatal(err) }
defer sess.Close()

_, err = sess.Turn(ctx, "What does this repo do?", func(ev abox.Event) {
    if ev.Kind == "text" { fmt.Print(ev.Text) }
})

Isolation claims stay Planned until the platform-specific Phase 0.5 and Phase 18 hardware suites in PLAN.md pass. The SDK boots the same microVM as the CLI. A current guest speaks protocol 4. Open / Resume reject older disks.

What the SDK does

Capability	Detail
Session	Snapshot a source directory, clone the golden disk, and boot libkrun
Turn	Stream text / tool / result / done events; optional usage
Cancel	ctx cancel → cancel_turn; kills in-flight run_command
Tools	Guest list_files, read_file, search, apply_patch, run_command + host-brokered MCP
Approvals	SetApprover for model-authored run_command (default deny)
Resume	Boot an existing root.raw by session id (Resume, same as abox --resume <id>)
Probe	ListFiles / ReadFile / RunCommand without a model turn

What it does not do

• No host-side tool loop. Tools execute in the guest only.
• No write_file. Edits go through apply_patch.
• No Docker on the session path. macOS uses Docker only to pack the golden .raw; Linux has a rootless native image builder.
• The Linux/KVM host path is implemented but runtime/release support remains Planned pending the pinned Arch/Fedora hardware gate. Windows is unsupported.
• No guest NIC and no TSI inet. LLM and MCP HTTPS are host-brokered.
• No MCP tool approval yet. Only run_command prompts.

Runtime pieces

your process  (pkg/abox or abox)
  → host LLM broker     (provider HTTPS; keys stay here)
  → host MCP broker     (Streamable HTTP; tokens stay here)
  → abox-vmm
      → libkrun + libkrunfw   ← Linux kernel (not on the disk)
      → Hypervisor.framework (macOS) / KVM (Linux, Planned support)
      → vsock only (krun_add_vsock flags 0)
  guest: /dev/vda = session root.raw (ext4 userspace)
         /dev/vdb = config.raw (session id + model alias; no secrets)
         process: /usr/local/bin/abox-guest

Next

1. Quickstart — install, key, first turn
2. Platforms — build baselines and support gates
3. Concepts — host vs guest, protocol 4
4. CLI and TUI — abox, slash commands, keys
5. API — Open, Turn, SetApprover, …
6. Troubleshooting