Get Started
REFERENCE

Go SDK

Call run9 from Go with the public SDK instead of shelling out to the CLI.

The CLI is built on a public Go SDK. Use the SDK when a service or agent harness creates boxes, runs commands, and forks snaps from its own code.

Install

go get github.com/sys9-ai/run9-sdk-go@latest

The module is github.com/sys9-ai/run9-sdk-go and the package name is run9. Releases use semantic version tags; pin one in go.mod.

Create a client

package main

import (
	"context"
	"log"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		log.Fatal(err)
	}

	project := client.WithProject("default")
	boxes, err := project.ListBoxes(context.Background(), run9.ListBoxesRequest{})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("loaded %d boxes", len(boxes))
}

The credentials are the same API key pair that Authenticate uses for the CLI.

Calling model

  • Create one client from the endpoint and credentials.
  • Call client.WithProject(...) before anything that lives in a project: boxes, snaps, execs, prewarm profiles, and secrets.
  • Use the base client for account, org, Shared Snap, and project discovery calls.
  • Streaming calls such as exec output come back through typed helpers, not raw frames.

The SDK covers the same features as the CLI, including Volumes, forks from running boxes, prewarm recording, background execs, and read-only file access to boxes and snaps.

Full reference