sandbox

type Box struct {
	InstanceID  string `` /* 188-byte string literal not displayed */
	Name        string `json:"name" jsonschema:"the backend instance name"`
	BoxID       string `json:"box_id,omitempty" jsonschema:"the box ID the caller assigned, if any (also set as the box hostname)"`
	Description string `json:"description,omitempty" jsonschema:"the caller-supplied description label, if any"`
	Spoke       string `json:"spoke,omitempty" jsonschema:"the cluster spoke the box runs on"`
	Image       string `json:"image" jsonschema:"the image or rootfs the box runs (may be empty for backends without an image concept)"`
	State       string `` /* 171-byte string literal not displayed */
	Status      string `json:"status" jsonschema:"a human readable status string"`
	Phase       string `json:"phase,omitempty" jsonschema:"broken when the box's init script failed during creation; empty otherwise"`
	LastError   string `json:"last_error,omitempty" jsonschema:"the init script's captured output when the box is broken; empty otherwise"`
	Created     int64  `json:"created" jsonschema:"creation time as a unix timestamp"`
	LastSeen    int64  `` /* 132-byte string literal not displayed */
}

type CreateOptions struct {
	// BoxID is the caller-assigned identifier for the box. When set, it is also
	// applied as the box's hostname (what `hostname` reports inside it), so it must
	// be a valid hostname label. It must be unique across managed boxes.
	BoxID string
	// Description is a free-form label shown by list/get to help the caller tell
	// boxes apart. It has no effect on the box itself.
	Description string
	// SpokeName selects which cluster spoke the box is created on (empty means the
	// admin-chosen default spoke). It is routing metadata used by the server's
	// cluster layer; the box backend itself ignores it.
	SpokeName string
	// Files are written into the box's filesystem after it is created but before
	// it starts, so they are present when the entrypoint runs. Used to inject
	// per-box secrets (e.g. a granular subject token) without baking them into
	// the image or an env var where the backend's introspection would expose them.
	Files []InjectFile
	// DiskBytes is the caller-requested size of the box's writable disk, in bytes
	// (0 = use the spoke's configured default). A backend that grows a per-box disk
	// (the Firecracker microVM, whose rootfs is a resizable raw block device) floors
	// it at the base image size and clamps it to the spoke's Limits.MaxDiskBytes cap,
	// so this unauthenticated create input can never request an unbounded disk. The
	// Docker backend has no such per-box block device and ignores it.
	DiskBytes int64
}

type CreateResult struct {
	// InstanceID is the box's opaque backend generation token.
	InstanceID string `json:"instance_id"`
	// InitScriptFailed is true when the box's init script failed. The box was still
	// provisioned and is left running so the failure can be inspected.
	InitScriptFailed bool `json:"init_script_failed,omitempty"`
	// InitScriptOutput is the init script's captured output (and failure reason),
	// set only when InitScriptFailed is true.
	InitScriptOutput string `json:"init_script_output,omitempty"`
	// PublishPorts are the in-box TCP ports the spoke is configured to expose as
	// HTTP proxies for every box it creates (the spoke's --publish-port). They are
	// returned so the hub — which owns proxy state — can publish them right after it
	// registers the box, when the box id, spoke, and generation are all known. Empty
	// for a spoke with no configured ports or a box that failed to come up.
	PublishPorts []PublishPort `json:"publish_ports,omitempty"`
}

type ExecResult struct {
	Stdout   string `json:"stdout" jsonschema:"the command's standard output"`
	Stderr   string `json:"stderr" jsonschema:"the command's standard error"`
	ExitCode int    `json:"exit_code" jsonschema:"the command's exit code (0 means success)"`
}

type InjectFile struct {
	Path    string
	Content []byte
	Mode    int64
	UID     int
	GID     int
}

type Limits struct {
	// MemoryBytes is the hard memory limit per box, in bytes (0 = unlimited).
	// Backends map it onto their own primitive (a cgroup memory cap for
	// containers, the VM's guest memory size for a microVM).
	MemoryBytes int64
	// NanoCPUs is the CPU quota per box in units of 1e-9 CPUs, i.e. 1_000_000_000
	// is one full CPU (0 = unlimited). Backends map it onto a CPU quota or a
	// rounded vCPU count as appropriate.
	NanoCPUs int64
	// PidsLimit caps the number of processes/threads in a box, blunting fork
	// bombs (0 = unlimited). Backends without a native process cap may ignore it.
	PidsLimit int64
	// MaxBoxes caps how many managed boxes may exist at once; Create rejects a new
	// box once the count is reached (0 = unlimited).
	MaxBoxes int
	// DiskBytes is the default writable-disk size, in bytes, applied to a box whose
	// create request names none (CreateOptions.DiskBytes == 0). Only a backend that
	// grows a per-box disk (Firecracker) uses it; 0 leaves the box at its base image
	// size (no grow).
	DiskBytes int64
	// MaxDiskBytes is the hard ceiling on a create request's DiskBytes, in bytes
	// (0 = no ceiling). It bounds the disk a caller on the by-design-unauthenticated
	// create path can request, mirroring the memory/CPU caps above.
	MaxDiskBytes int64
}

type PublishPort struct {
	// Port is the TCP port inside the box to expose (1-65535).
	Port int `json:"port"`
	// Description is an optional note recorded on the proxy (e.g. the service name).
	Description string `json:"description,omitempty"`
}