sandbox

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 27, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

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

Index

Constants

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

Variables

View Source 
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")
)
View Source 
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.

Functions

This section is empty.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package daytona contains Daytona execution-sandbox provider code.
 Package daytona contains Daytona execution-sandbox provider code.
cmd/agh-daytona-sidecar command
Package local implements the daemon-host execution sandbox provider.
 Package local implements the daemon-host execution sandbox provider.
Package providertest contains reusable provider conformance checks.
 Package providertest contains reusable provider conformance checks.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.