providersdk

type AllocationResult ¶ added in v0.1.40

type AllocationResult struct {
	Properties      map[string]any
	GuestCredential *GuestCredential
	AppliedPackages []resourcepack.AppliedPackage
}

AllocationResult separates safe properties, which may be persisted on a resource, from an ephemeral credential that must never enter resource metadata or the durable store.

type AvailabilityReporter ¶ added in v0.1.37

type AvailabilityReporter interface {
	Availability(ctx context.Context) (*ResourceAvailability, error)
}

AvailabilityReporter is an optional provider capability for reporting current resource headroom before a Create is attempted. Not every driver implements it — callers that care must type-assert, the same pattern as GuestPersonalizer.

type CIDRConflictError ¶ added in v0.1.70

type CIDRConflictError struct {
	RequestedCIDR   string
	ConflictingWith string
}

CIDRConflictError indicates a NetworkIsolator refused a caller-proposed segment CIDR because that range is already in use on this host by something the caller cannot see -- another Docker network, an existing NAT prefix, a host interface address, a VPN route. The caller is expected to propose a different range rather than treat this as fatal.

It exists because segment CIDR allocation is split across two parties that each hold half the information (#370): the daemon knows which ranges are in use across *all* hosts, which is what cross-host mesh peering requires, but only the agent knows what else already occupies that range on its own host. Both collision types are real and neither side can rule out the other's alone.

ConflictingWith is a human-readable description of what the range collided with, for diagnostics -- it is deliberately not structured, since every provider reports a different kind of object. Both fields are plain strings so the type round-trips through json.Marshal across the RemoteAgent/gRPC boundary, same as OrphanedResourceError.

func (e *CIDRConflictError) Error() string

func (e *CIDRConflictError) ErrorType() string

type CapacityError ¶ added in v0.1.39

type CapacityError struct {
	RequestedMemoryMB int64
	AvailableMemoryMB int64
}

CapacityError indicates the host does not currently have enough available capacity (e.g. memory) to satisfy a Create request. Provider-neutral: any driver can return one, not just Hyper-V, which aliases this type — see pkg/providersdk/providers/hyperv/driver.go.

func (e *CapacityError) Error() string

func (e *CapacityError) ErrorType() string

type Driver ¶

type Driver interface {
	// Type returns the provider type identifier (e.g. "docker", "hyperv").
	Type() Type

	// Create provisions a new resource from the given configuration.
	// The config is the driver's own typed struct, already unmarshaled.
	Create(ctx context.Context, cfg any) (*Resource, error)

	// Read returns the current status of a resource.
	Read(ctx context.Context, id string) (*ResourceStatus, error)

	// Update performs an operation on an existing resource. What "update"
	// means depends on the resource type: exec a command in a container,
	// set permissions on a share, attach a node to a network, etc.
	Update(ctx context.Context, id string, op Operation) (*Result, error)

	// Delete destroys a resource and cleans up associated state.
	//
	// Delete must be idempotent for missing provider resources: if the resource
	// is already gone, return nil. Boxy may retry cleanup after partially
	// completed state updates.
	Delete(ctx context.Context, id string) error

	// Allocate is called when a resource transitions from ready to allocated
	// (i.e., when it is assigned to a sandbox). It performs allocation-time
	// work such as generating credentials or injecting SSH keys.
	//
	// Returns additional Properties to merge into the resource.
	// Returns nil, nil if no allocation work is needed.
	Allocate(ctx context.Context, id string) (map[string]any, error)
}

Driver is the CRUD interface that every provider driver implements.

A driver is a thin adapter between Boxy and the underlying infrastructure (Docker, Hyper-V, VMware, etc.). It uses its native mechanism for all operations — the same client that creates resources also reads, updates, and deletes them.

Create and Delete manage resource lifecycle. Read checks current state. Update performs post-creation operations through the driver's native mechanism (docker exec, PowerShell Direct, VMware Tools, SSH, etc.).

type ErrorTyper ¶ added in v0.1.39

type ErrorTyper interface {
	ErrorType() string // e.g. "capacity"
}

ErrorTyper lets a driver error self-report a stable category (and, via json.Marshal on the error value itself, a JSON detail payload) for propagation across the RemoteAgent/gRPC boundary — without coupling the provider-neutral agentsdk layer to any specific driver package. Optional: errors that don't implement it just lose their type on that path, same as before this existed. See docs/superpowers/specs/2026-08-13-hyperv-create-failure-hardening-design.md.

type ExecOperation ¶ added in v0.1.34

type ExecOperation struct {
	Command []string `json:"command,omitempty"`
	// CommandText is an opaque command supplied as one string. Providers that
	// support it must pass it through their native command-text mechanism; it
	// must never be split and reconstructed as argv by the control plane.
	CommandText     string            `json:"command_text,omitempty"`
	Script          *ScriptSpec       `json:"script,omitempty"`
	Env             map[string]string `json:"env,omitempty"`
	GuestCredential *GuestCredential  `json:"guest_credential,omitempty"`
}

ExecOperation is the provider-neutral command shape used by Boxy workflows. Providers may alias or translate it into their native operation type.

type GuestAccessDetails ¶

type GuestAccessDetails struct {
	Properties map[string]string
}

GuestAccessDetails is the safe provider-returned connection metadata for a personalized guest. These values may be persisted and surfaced to the CLI.

func (d GuestAccessDetails) ToProperties() map[string]any

type GuestBootstrapCredential ¶ added in v0.1.40

type GuestBootstrapCredential struct {
	Username string
	Password string
}

GuestBootstrapCredential is the short-lived input used by a provider to authenticate to a freshly provisioned guest before rotating its password. It is never persisted in resource metadata.

type GuestBootstrapResolver ¶ added in v0.1.40

type GuestBootstrapResolver func(ctx context.Context, resourceID string) (GuestBootstrapCredential, error)

GuestBootstrapResolver supplies the server-owned bootstrap credential for a resource. Providers receive it as a callback so embedded and remote agents can use different transport implementations without changing driver APIs.

type GuestCredential ¶ added in v0.1.40

type GuestCredential struct {
	Kind string          `json:"kind"`
	Data json.RawMessage `json:"data"`
}

GuestCredential is an opaque, driver-defined credential payload. The control plane relays it without interpreting Data; Kind is advisory for clients that know how to render or persist a particular credential kind.

type GuestPersonalizationOptions ¶ added in v0.1.67

type GuestPersonalizationOptions struct {
	// ApplyNetwork marks an allocation-time personalization — a sandbox is
	// actually claiming this resource — as opposed to an admission-time (pool
	// preheat) or promotion-time one, which must leave it false.
	//
	// It no longer describes in-guest IP assignment. A driver declaring
	// NetworkIsolator addresses a claimed guest from its sandbox's segment in
	// AttachToSegment instead, so there is no pool-declared address left for
	// PersonalizeGuest to apply (#224). What the flag gates now is anything a
	// driver may only do because an allocation is in flight — concretely, the
	// Hyper-V driver retains the credential it rotated the guest onto just
	// long enough for that allocation's AttachToSegment to authenticate with
	// it, and retains nothing for a preheated resource nothing is going to
	// attach.
	//
	// Credential rotation and verification themselves always run regardless
	// of this flag — PowerShell Direct/VMBus guest exec needs no network.
	// The underlying principle is unchanged from #358: a
	// preheated-but-unclaimed resource gets nothing it has no use for yet,
	// whether that is an address or a retained secret. See ADR-0012's 2026-09
	// change note and ADR-0021's 2026-09-14 entry.
	ApplyNetwork bool
}

GuestPersonalizationOptions carries phase-dependent behavior for a PersonalizeGuest call. It is a struct rather than a positional bool so a future phase-dependent step gets a new field instead of another positional argument.

type GuestPersonalizationResult ¶

type GuestPersonalizationResult struct {
	AccessDetails       GuestAccessDetails
	EphemeralCredential *GuestCredential
}

GuestPersonalizationResult is the typed result of allocation-time guest personalization. AccessDetails may be persisted; EphemeralCredential must remain process-local and be delivered to the caller exactly once.

type GuestPersonalizer ¶

type GuestPersonalizer interface {
	PersonalizeGuest(ctx context.Context, id string, opts GuestPersonalizationOptions) (*GuestPersonalizationResult, error)
}

GuestPersonalizer is an optional provider capability for guest personalization with typed, safe returned access details. The same method is used at both admission time (pool preheat) and allocation time (a sandbox claiming the resource); opts.ApplyNetwork distinguishes them.

type Instance ¶

type Instance struct {
	Name   string         `json:"name" yaml:"name"`
	Type   Type           `json:"type" yaml:"type"`
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
}

Instance is a configured provider — a named, typed instance with its raw config. These are declared in the boxy.yaml providers: list and passed to ValidateInstances.

type MeshPeerer ¶ added in v0.1.68

type MeshPeerer interface {
	MeshIdentity(ctx context.Context, ref SegmentRef) (publicKey, endpoint, cidr string, err error)
	AddMeshPeer(ctx context.Context, ref SegmentRef, peerPublicKey, peerEndpoint, peerCIDR string) error
	RemoveMeshPeer(ctx context.Context, ref SegmentRef, peerPublicKey string) error
}

MeshPeerer is an optional provider capability for cross-host connectivity between two sandboxes' segments on different hosts (spec Decision 2). Not every driver implements it -- callers must type-assert, the same pattern as every other optional capability in this package.

MeshIdentity is the first call for a given segment: it lazily creates the segment's mesh interface if one doesn't exist yet, and returns what a remote peer needs to connect to it -- a public key (never a private key; see pkg/meshnet's key-handling guarantee), a host:port endpoint, and the segment's own subnet CIDR (so the *other* side knows what to route through this peer once it, in turn, calls AddMeshPeer).

AddMeshPeer/RemoveMeshPeer operate on a segment that MUST have already had MeshIdentity called for it at least once -- calling either on a segment with no mesh interface yet is a caller error, not something to silently no-op.

type NetworkIsolator ¶ added in v0.1.68

type NetworkIsolator interface {
	// CreateSegment creates a new, empty private network segment for the
	// given sandbox. Called once per sandbox, on its first resource claim.
	//
	// Idempotent per sandboxID: repeated calls for the same sandbox return
	// the same SegmentRef without erroring, rather than creating a second
	// segment. Callers therefore retry a failed or interrupted CreateSegment
	// freely; an implementation that created a fresh segment each time would
	// strand the earlier ones, since only the ref the caller ends up holding
	// is ever passed to DestroySegment.
	//
	// sandboxID is expected to already be safe for use inside a
	// provider-specific resource name -- no spaces, and restricted to
	// DNS-label-safe characters. Boxy's own sandbox IDs satisfy this by
	// construction, so implementations are not required to sanitize or
	// escape it further; they may derive a deterministic switch/network name
	// from it directly.
	//
	// cidr is the address range the caller has allocated for this segment,
	// in CIDR notation. The implementation must use it rather than choosing
	// its own: the caller allocates globally across every host so that a
	// sandbox spanning two hosts gets two non-overlapping segments, which is
	// what cross-host mesh peering requires (#370). A driver that picks its
	// own range independently will collide with the other host sooner or
	// later, and that host then routes traffic for the peer's segment
	// locally instead of into the tunnel.
	//
	// The implementation must check cidr against what already exists on its
	// own host -- other networks, NAT prefixes, interface addresses -- and
	// return a *CIDRConflictError if it is unusable, rather than creating a
	// segment that overlaps something local. The caller responds by
	// proposing a different range. Only the agent can see this class of
	// conflict; only the caller can see the cross-host class.
	//
	// On the idempotent repeat path, an implementation that already has a
	// segment for sandboxID returns it unchanged and ignores cidr — the
	// existing segment's range is authoritative, and a caller re-proposing
	// a different one must not silently renumber a live network. The
	// returned string is always that authoritative range, whether it came
	// from the cidr argument (fresh segment) or from the pre-existing one
	// (idempotent repeat): the caller must persist this value rather than
	// assuming its own proposal was honored, or a retry can record a range
	// nothing actually holds while the real one goes untracked.
	CreateSegment(ctx context.Context, sandboxID string, cidr string) (SegmentRef, string, error)

	// AttachToSegment moves an already-created resource (identified by the
	// driver's own provider-specific resource ID, as returned in
	// Resource.ID from Driver.Create) onto the given segment.
	//
	// Idempotent: calling it again on a resource already attached to ref is
	// not an error. A retry after a partially-applied attach must converge
	// on the same end state -- the resource on ref and off everything else --
	// rather than failing because some of that work was already done.
	AttachToSegment(ctx context.Context, providerResourceID string, ref SegmentRef) error

	// DestroySegment tears down a segment created by CreateSegment. Must be
	// idempotent for an already-gone segment, matching Driver.Delete's
	// idempotency contract.
	DestroySegment(ctx context.Context, ref SegmentRef) error
}

NetworkIsolator is an optional provider capability for per-sandbox network isolation. Not every driver implements it — callers that care must type-assert, the same pattern as AvailabilityReporter, ResourceLister, GuestPersonalizer, and NetworkRangeReporter.

Segment creation cannot happen at Driver.Create time: Boxy provisions resources into a pool's ready inventory ahead of any sandbox (preheat), and a sandbox later claims an already-created resource via a separate allocation step. CreateSegment is therefore called once, on a sandbox's first resource claim; AttachToSegment moves each claimed resource off whatever pool-level network it was created on and onto the sandbox's segment, at allocation time. AttachToSegment must be fast — a single lightweight reconnect, not a provisioning-style operation — because sandboxes need to be ready near-instantly.

type NetworkRange ¶ added in v0.1.46

type NetworkRange struct {
	// CIDR is the discovered IPv4 subnet in canonical network-address form
	// (e.g. "203.0.113.0/24").
	CIDR string `json:"cidr"`

	// Gateway is the host-side address on the switch's own interface within
	// CIDR, when known (e.g. "203.0.113.1"). Empty if undetermined.
	Gateway string `json:"gateway,omitempty"`

	// NATBacked reports whether the driver could positively confirm CIDR is
	// backed by a NAT rule (e.g. a Get-NetNat entry) rather than a plain
	// internal/private switch with no NAT. False means "not confirmed", not
	// "confirmed absent" — a driver that can't correlate NAT rules to a
	// switch at all should leave this false rather than guess.
	NATBacked bool `json:"nat_backed,omitempty"`
}

NetworkRange describes one IPv4 subnet a provider discovered bound to a named virtual switch/network on its host, as opposed to an operator-declared range in pool config. Fields are best-effort: a driver may be unable to determine Gateway or confirm NATBacked even when CIDR itself is known, so callers should not assume every field is populated.

type NetworkRangeReporter ¶ added in v0.1.46

type NetworkRangeReporter interface {
	NetworkRanges(ctx context.Context, switchName string) ([]NetworkRange, error)
}

NetworkRangeReporter is an optional provider capability for discovering the real IPv4 range(s) a named switch/network has bound on the host, distinct from whatever range an operator declared in pool config. Not every driver implements it — callers that care must type-assert, the same pattern as AvailabilityReporter, ResourceLister, and GuestPersonalizer.

The intended use is a driver validating its own pool config against live host state before provisioning — not a general "hardware inventory" subsystem. A switch name that doesn't exist, or exists but has no discoverable IPv4 range (e.g. a Private switch with no host vNIC), is not itself an error: implementations should return (nil, nil) for "nothing found" and reserve a non-nil error for a query that could not be completed at all.

type Operation ¶

type Operation interface{}

Operation is the input to Driver.Update. Each driver defines its own concrete operation types.

type OrphanedResourceError ¶ added in v0.1.39

type OrphanedResourceError struct {
	ID           string
	CauseMessage string
}

OrphanedResourceError indicates Create failed and best-effort cleanup of the partially-created resource also failed, leaving it on the underlying host outside Boxy's inventory. ID is the provider-native identifier — the same convention every successfully created Resource uses — so a caller can record a quarantined resource and retry destroying it later. CauseMessage is a plain string, not a wrapped error, so this type round-trips through json.Marshal/json.Unmarshal across the RemoteAgent/gRPC boundary (see #185) — an error interface's concrete type usually can't survive that.

func (e *OrphanedResourceError) Error() string

func (e *OrphanedResourceError) ErrorType() string

type Registration ¶

type Registration struct {
	// Type is the provider type identifier (e.g. "docker", "hyperv").
	Type Type

	// ConfigProto returns a zero-value config struct for this driver type.
	// The system unmarshals a provider instance's config YAML block into this
	// struct before calling NewDriver.
	ConfigProto func() any

	// NewDriver creates a Driver instance from a parsed config struct.
	// The cfg argument is the same type returned by ConfigProto, populated
	// by the YAML unmarshaler.
	NewDriver func(cfg any) (Driver, error)
}

Registration bundles everything a provider type contributes to the system: a config prototype for unmarshaling provider-instance config, and a factory that produces a Driver from parsed config. Pool-level create settings are decoded separately by each driver's Create method.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry maps provider Type -> Registration.

func NewRegistry() *Registry

func (r *Registry) Get(t Type) (Registration, bool)

func (r *Registry) NewDriverFromInstance(instance Instance, baseDir string) (Driver, error)

func (r *Registry) Register(reg Registration) error

func (r *Registry) Types() []Type

func (r *Registry) ValidateInstances(_ context.Context, instances []Instance) error

type RelativePathResolver ¶ added in v0.1.42

type RelativePathResolver interface {
	ResolveRelativePaths(baseDir string)
}

RelativePathResolver is an optional capability for a provider Config type that has one or more filesystem path fields it wants resolved relative to the boxy config file's own directory, rather than left to resolve against whatever the process's ambient working directory happens to be. This mirrors how Boxy's own .boxy/state.json is resolved (see internal/cli/serve.go's serveStatePath) — a relative path in a config file should mean the same thing regardless of where the process was launched from.

Registry.NewDriverFromInstance calls ResolveRelativePaths (if the decoded config implements it) with baseDir before constructing the driver. baseDir is empty when no config file path is known (e.g. no --config flag, or config loaded from stdin); implementations should leave their paths untouched in that case rather than guessing a base.

Optional and type-asserted, like every other capability in this package (ResourceLister, AvailabilityReporter, GuestPersonalizer, ErrorTyper) — most provider Config types have no config-relative path fields and don't implement this. It's deliberately not the default for every path-shaped config field: docker's socket path and hyperv's VHD/template paths are real host filesystem locations an operator points at explicitly, not directories conceptually owned by the boxy config file the way devfactory's DataDir is.

type Resource ¶

type Resource struct {
	// ID is the provider-specific resource identifier
	// (container ID, VM name, etc.).
	ID string

	// ConnectionInfo describes how to reach the resource. Keys and values
	// are driver-defined (e.g. "host", "port", "container_id").
	ConnectionInfo map[string]string

	// Metadata holds additional driver-specific data that Boxy may
	// surface but does not interpret.
	Metadata map[string]string
}

Resource is returned by Driver.Create — the driver's output after provisioning a new resource.

type ResourceAvailability ¶ added in v0.1.37

type ResourceAvailability struct {
	// MemoryMB is available memory for new resources, in megabytes.
	MemoryMB int64 `json:"memory_mb"`
}

ResourceAvailability is a driver's point-in-time view of how much of a resource it can currently hand out to a new Create request.

type ResourceDialer ¶ added in v0.1.70

type ResourceDialer interface {
	DialResource(ctx context.Context, providerResourceID string, port int) (net.Conn, error)
}

ResourceDialer is an optional Driver capability: open a TCP connection from the host the driver runs on to one of its resources. It is what lets a client outside the host reach a resource on an isolated network, such as RDP, SSH, or WinRM into a sandboxed VM, by relaying through the host.

The driver resolves the resource's address itself. Callers pass a resource ID and a port, never an address, so a caller can't use the driver to reach anything other than its own resources.

type ResourceLister ¶ added in v0.1.29

type ResourceLister interface {
	List(ctx context.Context) ([]ResourceStatus, error)
}

ResourceLister is an optional provider capability for enumerating every resource the driver currently manages, independent of any single resource ID. Not every driver can support this (see docker's implementation for the managed-resource tagging convention this depends on) — callers must type- assert for it rather than relying on it being part of Driver.

type ResourceStatus ¶

type ResourceStatus struct {
	ID    string
	State string // Driver-defined: "running", "stopped", "error", etc.
}

ResourceStatus is returned by Driver.Read.

type Result ¶

type Result struct {
	// Outputs holds key/value pairs produced by the operation
	// (e.g. generated credentials, captured stdout).
	Outputs map[string]string
}

Result is returned by Driver.Update.

type ScriptInterpreter ¶ added in v0.1.59

type ScriptInterpreter string

ScriptInterpreter identifies the guest-side runner for a staged script.

const (
	ScriptInterpreterAuto       ScriptInterpreter = "auto"
	ScriptInterpreterPowerShell ScriptInterpreter = "powershell"
	ScriptInterpreterSH         ScriptInterpreter = "sh"
)

type ScriptSpec ¶ added in v0.1.59

type ScriptSpec struct {
	Content     []byte            `json:"content"`
	Digest      string            `json:"digest"`
	Interpreter ScriptInterpreter `json:"interpreter"`
	Args        []string          `json:"args,omitempty"`
}

ScriptSpec is provider-neutral metadata for a script staged on a guest. Content is intentionally carried only for the duration of execution; the control plane must not persist or log it.

func NewScriptSpec(content []byte, interpreter ScriptInterpreter, args []string) (*ScriptSpec, error)

func (s *ScriptSpec) Validate() error

func (s *ScriptSpec) VerifyDigest() error

type SecretRef ¶

type SecretRef string

SecretRef is an opaque provider-managed lookup handle for a secret.

The initial built-in resolver supports env:NAME references so providers can avoid persisting raw bootstrap secrets in resource metadata.

type SegmentRef ¶ added in v0.1.68

type SegmentRef string

SegmentRef is an opaque, provider-defined identifier for a per-sandbox network segment (a switch name for Hyper-V, a network ID for Docker). Callers never interpret it — they hold onto whatever CreateSegment returns and pass it back to AttachToSegment/DestroySegment unchanged.

type SourceDescriptor ¶ added in v0.1.63

type SourceDescriptor = artifact.SourceDescriptor

SourceDescriptor is the provider-neutral source handoff. The alias keeps provider packages independent from artifact registry implementations while allowing the registry and provider to share one wire shape.

type StreamingDriver ¶ added in v0.1.34

type StreamingDriver interface {
	UpdateStream(ctx context.Context, id string, op Operation, sink eventstream.Sink) (*Result, error)
}

StreamingDriver is an optional capability for providers that can emit live events while an operation runs. The base Driver contract remains unary so providers can opt in incrementally.

type Type ¶

type Type string

Type identifies the provider kind (e.g. "docker", "hyperv").