sandbox

Documentation

Overview

Package sandbox defines execution-sandbox contracts shared by daemon-native providers, session orchestration, and ACP launch plumbing.

Index

• Constants
• Variables
• type Backend
  • func (b Backend) Valid() bool
• type DaytonaConfig
• type DaytonaStartupSource
• type FindSandboxRequest
• type Finder
• type Handle
• type LaunchSpec
• type Launcher
• type NetworkPolicy
• type PermissionDecision
• type PermissionOperation
• type PersistenceMode
  • func (m PersistenceMode) Valid() bool
• type PrepareRequest
• type Prepared
• type Provider
• type Registry
  • func NewRegistry(providers ...Provider) (*Registry, error)
  • func (r *Registry) DefaultProvider() (Provider, error)
  • func (r *Registry) Provider(backend Backend) (Provider, error)
  • func (r *Registry) Providers() map[Backend]Provider
  • func (r *Registry) Register(provider Provider) error
• type Resolved
• type SessionState
• type SyncDirection
• type SyncMode
  • func (m SyncMode) Valid() bool
• type SyncOptions
• type SyncReason
• type SyncResult
• type ToolHost

Constants

const (
	// DefaultBackend is the execution backend used when no profile selects one.
	DefaultBackend = BackendLocal
)

Variables

var (
	// ErrNilProvider reports an attempt to register a nil provider.
	ErrNilProvider = errors.New("sandbox: provider is nil")
	// ErrInvalidProviderBackend reports that a provider returned an unknown backend.
	ErrInvalidProviderBackend = errors.New("sandbox: provider backend is invalid")
	// ErrProviderNotRegistered reports that no provider is registered for a backend.
	ErrProviderNotRegistered = errors.New("sandbox: provider not registered")
)

var ErrSandboxNotFound = errors.New("sandbox: remote sandbox not found")

ErrSandboxNotFound reports that a provider could not find a remote sandbox matching daemon-owned identity labels.

Types

type Backend

type Backend string

Backend identifies the execution sandbox backend implementation.

const (
	// BackendLocal runs agents as local daemon-host subprocesses.
	BackendLocal Backend = "local"
	// BackendDaytona runs agents inside Daytona sandboxes.
	BackendDaytona Backend = "daytona"
	// BackendE2B is reserved for a future E2B provider.
	BackendE2B Backend = "e2b"
)

func (Backend) Valid

func (b Backend) Valid() bool

Valid reports whether b is a known backend identifier.

type DaytonaConfig

type DaytonaConfig struct {
	APIURL        string
	Target        string
	Image         string
	Snapshot      string
	Class         string
	AutoStop      string
	AutoArchive   string
	StartupSource DaytonaStartupSource
	StartupRef    string
}

DaytonaConfig is the resolved Daytona-specific provider policy.

type DaytonaStartupSource

type DaytonaStartupSource string

DaytonaStartupSource identifies which Daytona startup input is authoritative.

const (
	// DaytonaStartupSourceImage starts a sandbox from an image.
	DaytonaStartupSourceImage DaytonaStartupSource = "image"
	// DaytonaStartupSourceSnapshot starts a sandbox from a pre-baked snapshot.
	DaytonaStartupSourceSnapshot DaytonaStartupSource = "snapshot"
)

type FindSandboxRequest

type FindSandboxRequest struct {
	SessionID           string
	WorkspaceID         string
	SandboxID           string
	LocalRootDir        string
	LocalAdditionalDirs []string
	Sandbox             Resolved
	ProviderState       json.RawMessage
	Labels              map[string]string
}

FindSandboxRequest carries daemon identity for provider-side lookup of a partially-created remote sandbox.

type Finder

type Finder interface {
	FindSandbox(ctx context.Context, req FindSandboxRequest) (SessionState, error)
}

Finder is optionally implemented by remote providers that can discover provider resources by daemon-owned identity labels.

type Handle

type Handle interface {
	PID() int
	Cwd() string
	Stdin() io.WriteCloser
	Stdout() io.ReadCloser
	Stderr() string
	Done() <-chan struct{}
	Wait() error
	Stop(ctx context.Context) error
}

Handle represents a running agent process.

type LaunchSpec

type LaunchSpec struct {
	Command        string
	Cwd            string
	AdditionalDirs []string
	Env            []string
}

LaunchSpec describes the ACP-capable command to start inside a sandbox.

type Launcher

type Launcher interface {
	Launch(ctx context.Context, spec LaunchSpec) (Handle, error)
}

Launcher starts an ACP-capable agent process inside a sandbox.

type NetworkPolicy

type NetworkPolicy struct {
	AllowPublicIngress bool
	AllowOutbound      bool
	AllowList          []string
	DenyList           []string
	Required           bool
}

NetworkPolicy is the resolved provider-neutral network intent.

type PermissionDecision

type PermissionDecision string

PermissionDecision is a daemon policy decision for an ACP permission request.

const (
	// PermissionDecisionPending asks an operator or client to decide.
	PermissionDecisionPending PermissionDecision = "pending"
	// PermissionDecisionAllowOnce permits one operation.
	PermissionDecisionAllowOnce PermissionDecision = "allow-once"
	// PermissionDecisionAllowAlways permits this class of operation persistently.
	PermissionDecisionAllowAlways PermissionDecision = "allow-always"
	// PermissionDecisionRejectOnce rejects one operation.
	PermissionDecisionRejectOnce PermissionDecision = "reject-once"
	// PermissionDecisionRejectAlways rejects this class of operation persistently.
	PermissionDecisionRejectAlways PermissionDecision = "reject-always"
)

type PermissionOperation

type PermissionOperation string

PermissionOperation identifies a ToolHost operation subject to policy.

const (
	// PermissionOperationReadTextFile authorizes ACP text file reads.
	PermissionOperationReadTextFile PermissionOperation = "fs/read_text_file"
	// PermissionOperationWriteTextFile authorizes ACP text file writes.
	PermissionOperationWriteTextFile PermissionOperation = "fs/write_text_file"
	// PermissionOperationCreateTerminal authorizes terminal creation.
	PermissionOperationCreateTerminal PermissionOperation = "terminal/create"
	// PermissionOperationRequestToolGrant authorizes interactive permission requests.
	PermissionOperationRequestToolGrant PermissionOperation = "session/request_permission"
)

type PersistenceMode

type PersistenceMode string

PersistenceMode controls whether provider instances are reused or discarded.

const (
	// PersistenceTransient destroys the runtime sandbox when the session stops.
	PersistenceTransient PersistenceMode = "transient"
	// PersistenceReuse keeps the runtime sandbox available for reuse.
	PersistenceReuse PersistenceMode = "reuse"
	// PersistenceArchive archives the runtime sandbox when possible.
	PersistenceArchive PersistenceMode = "archive"
)

func (PersistenceMode) Valid

func (m PersistenceMode) Valid() bool

Valid reports whether m is a known persistence mode.

type PrepareRequest

type PrepareRequest struct {
	SessionID           string
	WorkspaceID         string
	SandboxID           string
	InstanceID          string
	LocalRootDir        string
	LocalAdditionalDirs []string
	Sandbox             Resolved
	AgentCommand        string
	AgentEnv            []string
	Permissions         string
	ResumeACPState      string
	ProviderState       json.RawMessage
}

PrepareRequest carries all daemon state needed to prepare a sandbox.

type Prepared

type Prepared struct {
	State                 SessionState
	RuntimeRootDir        string
	RuntimeAdditionalDirs []string
	Launcher              Launcher
	Launch                LaunchSpec
	ToolHost              ToolHost
}

Prepared is the result of preparing an execution sandbox for a session.

type Provider

type Provider interface {
	Backend() Backend
	Prepare(ctx context.Context, req PrepareRequest) (Prepared, error)
	SyncToRuntime(ctx context.Context, state SessionState, opts SyncOptions) (SyncResult, error)
	SyncFromRuntime(ctx context.Context, state SessionState, opts SyncOptions) (SyncResult, error)
	Destroy(ctx context.Context, state SessionState) error
}

Provider manages the lifecycle of an execution sandbox.

type Registry

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

Registry resolves sandbox providers by backend.

func NewRegistry

func NewRegistry(providers ...Provider) (*Registry, error)

NewRegistry constructs a provider registry populated with the supplied providers.

func (*Registry) DefaultProvider

func (r *Registry) DefaultProvider() (Provider, error)

DefaultProvider returns the provider registered for the default backend.

func (*Registry) Provider

func (r *Registry) Provider(backend Backend) (Provider, error)

Provider returns the provider registered for backend.

func (*Registry) Providers

func (r *Registry) Providers() map[Backend]Provider

Providers returns a snapshot of registered providers keyed by backend.

func (*Registry) Register

func (r *Registry) Register(provider Provider) error

Register adds or replaces the provider for its backend.

type Resolved

type Resolved struct {
	Profile        string
	Backend        Backend
	SyncMode       SyncMode
	Persistence    PersistenceMode
	RuntimeRootDir string
	DestroyOnStop  bool
	Env            map[string]string
	SecretEnv      map[string]string
	Network        NetworkPolicy
	Daytona        *DaytonaConfig
}

Resolved is the workspace-selected sandbox profile after defaults and backend policy have been applied.

type SessionState

type SessionState struct {
	SandboxID             string
	Backend               Backend
	Profile               string
	State                 string
	InstanceID            string
	RuntimeRootDir        string
	RuntimeAdditionalDirs []string
	ProviderState         json.RawMessage
	SSHAccessExpiresAt    *time.Time
	PreparedAt            time.Time
}

SessionState is the provider runtime state persisted for a session.

type SyncDirection

type SyncDirection string

SyncDirection identifies the direction of a workspace synchronization.

const (
	// SyncDirectionToRuntime syncs local workspace files into the runtime.
	SyncDirectionToRuntime SyncDirection = "to_runtime"
	// SyncDirectionFromRuntime syncs runtime workspace files back to local storage.
	SyncDirectionFromRuntime SyncDirection = "from_runtime"
)

type SyncMode

type SyncMode string

SyncMode controls workspace synchronization between local and runtime roots.

const (
	// SyncModeNone disables automatic workspace synchronization.
	SyncModeNone SyncMode = "none"
	// SyncModeSessionBidirectional syncs local-to-runtime on start and runtime-to-local on stop.
	SyncModeSessionBidirectional SyncMode = "session-bidirectional"
	// SyncModeTurnBidirectional is reserved for future turn-boundary synchronization.
	SyncModeTurnBidirectional SyncMode = "turn-bidirectional"
)

func (SyncMode) Valid

func (m SyncMode) Valid() bool

Valid reports whether m is a known sync mode.

type SyncOptions

type SyncOptions struct {
	Reason          SyncReason
	ExcludePatterns []string
}

SyncOptions carries daemon decisions that affect one provider sync run.

type SyncReason

type SyncReason string

SyncReason explains why a provider sync operation is running.

const (
	// SyncReasonStart syncs before launching the agent.
	SyncReasonStart SyncReason = "start"
	// SyncReasonTurn is reserved for future turn-boundary synchronization.
	SyncReasonTurn SyncReason = "turn"
	// SyncReasonStop syncs during normal session stop.
	SyncReasonStop SyncReason = "stop"
	// SyncReasonCrash syncs during crash recovery.
	SyncReasonCrash SyncReason = "crash"
)

type SyncResult

type SyncResult struct {
	FilesSynced      int
	BytesTransferred int64
	Errors           []string
}

SyncResult reports provider-observed transfer statistics.

type ToolHost

type ToolHost interface {
	ReadTextFile(ctx context.Context, path string) (string, error)
	WriteTextFile(ctx context.Context, path string, content string) error
	ResolvePath(path string) (string, error)
	Authorize(op PermissionOperation) error
	PermissionDecision(req acpsdk.RequestPermissionRequest) (PermissionDecision, bool)
	CreateTerminal(ctx context.Context, req acpsdk.CreateTerminalRequest) (acpsdk.CreateTerminalResponse, error)
	KillTerminal(id string) error
	TerminalOutput(id string) (string, error)
	WaitForTerminalExit(ctx context.Context, id string) (int, error)
	ReleaseTerminal(id string) error
}

ToolHost abstracts ACP file, permission, and terminal operations for a runtime.