runtime

Documentation

Overview

Package runtime defines abstractions for executing commands and accessing the filesystem in different isolation environments (host, docker, podman, etc.).

Package runtime provides the execution and workspace abstraction used to run tool commands either on the host or inside an isolated container runtime.

The package is consumed through RuntimeResolver implementations. Most callers use NewResolver() together with config.ContainerConfig:

resolver := runtime.NewResolver()
execRuntime, workspaceFS, err := resolver.Resolve(cfg.Container)

Resolve returns both an ExecutionRuntime for bash-style command execution and a WorkspaceFS that keeps file tools pointed at the same workspace. Host mode preserves the historical behaviour, while Docker and Podman use bind-mounted workspaces so view/write/edit/patch operate on the same files that commands see inside the container.

Container configuration lives under the [Container] section in .pando.toml. Supported keys are:

• runtime: host, docker, podman, embedded, or auto
• image, pull_policy, socket, work_dir
• network, read_only, user, cpu_limit, mem_limit, pids_limit
• no_new_privileges, allow_env, allow_mounts, extra_env, extra_mounts
• embedded_cache_dir, embedded_gc_keep_n

The secure defaults assume an isolated runtime: network access disabled, read-only root filesystem enabled, no-new-privileges enabled, and a PID cap of 512. These defaults reduce accidental network exfiltration, make root filesystem mutation explicit, and limit the blast radius of runaway or hostile processes. The workspace bind mount remains writable so normal tool editing flows still work.

When runtime is set to auto, the resolver prefers a rootless Podman socket, then Docker, and finally falls back to the host runtime. Manual selection is available for Docker, Podman, or the embedded runtime.

Index

• type ContainerEvent
• type EmbeddedRuntime
  • func (e *EmbeddedRuntime) Exec(ctx context.Context, sessionID, command string, env []string) (ExecResult, error)
  • func (e *EmbeddedRuntime) Kill(ctx context.Context, sessionID string) error
  • func (e *EmbeddedRuntime) Output(_ context.Context, sessionID string) (string, error)
  • func (e *EmbeddedRuntime) StartSession(ctx context.Context, sessionID, workDir string) error
  • func (e *EmbeddedRuntime) StopSession(ctx context.Context, sessionID string) error
  • func (e *EmbeddedRuntime) Type() RuntimeType
• type EventLog
  • func NewEventLog(max int) *EventLog
  • func (l *EventLog) Add(event ContainerEvent)
  • func (l *EventLog) List(limit int, sessionID string) []ContainerEvent
• type ExecResult
• type ExecutionRuntime
  • func NewDockerRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)
  • func NewEmbeddedRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)
  • func NewHostRuntime() ExecutionRuntime
  • func NewPodmanRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)
• type RuntimeCapabilities
  • func Discover() []RuntimeCapabilities
• type RuntimeResolver
  • func NewResolver() RuntimeResolver
• type RuntimeType
• type SecurityPolicy
  • func DefaultSecurityPolicy() SecurityPolicy
  • func PolicyFromConfig(cfg config.ContainerConfig) SecurityPolicy
• type SessionEntry
• type SessionManager
  • func DefaultSessionManager() *SessionManager
  • func NewSessionManager() *SessionManager
  • func (m *SessionManager) Events(limit int, sessionID string) []ContainerEvent
  • func (m *SessionManager) Get(sessionID string) (*SessionEntry, bool)
  • func (m *SessionManager) GetOrCreate(ctx context.Context, sessionID string, workDir string, ...) (*SessionEntry, error)
  • func (m *SessionManager) List() []SessionEntry
  • func (m *SessionManager) RecordEvent(event ContainerEvent)
  • func (m *SessionManager) Stop(ctx context.Context, sessionID string) error
  • func (m *SessionManager) StopAll(ctx context.Context) error
• type WorkspaceFS
  • func NewBindMountedContainerFS() WorkspaceFS
  • func NewContainerFS() WorkspaceFS
  • func NewCopyContainerFS() WorkspaceFS
  • func NewHostFS() WorkspaceFS

Types

type ContainerEvent

type ContainerEvent struct {
	SessionID   string      `json:"sessionId"`
	RuntimeType RuntimeType `json:"runtimeType"`
	ContainerID string      `json:"containerId,omitempty"`
	Event       string      `json:"event"`
	Timestamp   time.Time   `json:"timestamp"`
	Details     string      `json:"details,omitempty"`
}

type EmbeddedRuntime

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

EmbeddedRuntime executes commands against an unpacked OCI image without requiring a host-side Docker or Podman daemon. The current MVP uses a fallback strategy that prepares a rootfs and then executes commands via the host shell with the unpacked image exposed through PATH and bind-like symlinks. Namespace-based isolation can be added later without changing the public runtime interface.

func (*EmbeddedRuntime) Exec

func (e *EmbeddedRuntime) Exec(ctx context.Context, sessionID, command string, env []string) (ExecResult, error)

func (*EmbeddedRuntime) Kill

func (e *EmbeddedRuntime) Kill(ctx context.Context, sessionID string) error

func (*EmbeddedRuntime) Output

func (e *EmbeddedRuntime) Output(_ context.Context, sessionID string) (string, error)

func (*EmbeddedRuntime) StartSession

func (e *EmbeddedRuntime) StartSession(ctx context.Context, sessionID, workDir string) error

func (*EmbeddedRuntime) StopSession

func (e *EmbeddedRuntime) StopSession(ctx context.Context, sessionID string) error

func (*EmbeddedRuntime) Type

func (e *EmbeddedRuntime) Type() RuntimeType

type EventLog

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

func NewEventLog

func NewEventLog(max int) *EventLog

func (*EventLog) Add

func (l *EventLog) Add(event ContainerEvent)

func (*EventLog) List

func (l *EventLog) List(limit int, sessionID string) []ContainerEvent

type ExecResult

type ExecResult struct {
	Stdout      string
	Stderr      string
	ExitCode    int
	Interrupted bool
}

ExecResult holds the output of a single command execution.

type ExecutionRuntime

type ExecutionRuntime interface {
	// Exec runs cmd inside the session identified by sessionID.
	Exec(ctx context.Context, sessionID string, cmd string, env []string) (ExecResult, error)
	// StartSession initialises a new persistent session rooted at workDir.
	StartSession(ctx context.Context, sessionID string, workDir string) error
	// StopSession tears down the session and releases its resources.
	StopSession(ctx context.Context, sessionID string) error
	// Output returns any buffered output for the session.
	Output(ctx context.Context, sessionID string) (string, error)
	// Kill forcibly terminates the running command inside the session.
	Kill(ctx context.Context, sessionID string) error
	// Type returns the RuntimeType for this implementation.
	Type() RuntimeType
}

ExecutionRuntime handles command execution within a session.

func NewDockerRuntime

func NewDockerRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)

func NewEmbeddedRuntime

func NewEmbeddedRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)

NewEmbeddedRuntime returns a runtime that prefers the built-in OCI executor and falls back to Docker, Podman, then host execution if embedded session startup fails.

func NewHostRuntime

func NewHostRuntime() ExecutionRuntime

NewHostRuntime returns an ExecutionRuntime backed by the host shell.

func NewPodmanRuntime

func NewPodmanRuntime(cfg config.ContainerConfig) (ExecutionRuntime, error)

type RuntimeCapabilities

type RuntimeCapabilities struct {
	Type      RuntimeType `json:"type"`
	Available bool        `json:"available"`
	Exec      bool        `json:"exec"`
	FS        bool        `json:"fs"`
	Version   string      `json:"version,omitempty"`
	Socket    string      `json:"socket,omitempty"` // socket path for docker/podman
}

RuntimeCapabilities describes a discovered runtime and its capabilities.

func Discover

func Discover() []RuntimeCapabilities

Discover probes the host for available container runtimes and returns their capabilities. The host runtime is always reported as available.

type RuntimeResolver

type RuntimeResolver interface {
	// Resolve returns the ExecutionRuntime and WorkspaceFS for the given config.
	Resolve(cfg config.ContainerConfig) (ExecutionRuntime, WorkspaceFS, error)
	// Discover probes the host and returns capabilities for each known runtime.
	Discover() []RuntimeCapabilities
}

RuntimeResolver selects the appropriate runtime based on configuration.

func NewResolver

func NewResolver() RuntimeResolver

NewResolver returns the default RuntimeResolver.

type RuntimeType

type RuntimeType string

RuntimeType identifies the execution backend.

const (
	RuntimeHost     RuntimeType = "host"
	RuntimeDocker   RuntimeType = "docker"
	RuntimePodman   RuntimeType = "podman"
	RuntimeEmbedded RuntimeType = "embedded"
)

type SecurityPolicy

type SecurityPolicy struct {
	Network         string
	ReadOnly        bool
	User            string
	CPULimit        string
	MemLimit        string
	PidsLimit       int64
	AllowEnv        []string
	AllowMounts     []string
	NoNewPrivileges bool
}

func DefaultSecurityPolicy

func DefaultSecurityPolicy() SecurityPolicy

func PolicyFromConfig

func PolicyFromConfig(cfg config.ContainerConfig) SecurityPolicy

type SessionEntry

type SessionEntry struct {
	SessionID   string           `json:"sessionId"`
	RuntimeType RuntimeType      `json:"runtime"`
	Runtime     ExecutionRuntime `json:"-"`
	ContainerID string           `json:"containerId,omitempty"`
	WorkDir     string           `json:"workDir"`
	CreatedAt   time.Time        `json:"createdAt"`
}

type SessionManager

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

func DefaultSessionManager

func DefaultSessionManager() *SessionManager

func NewSessionManager

func NewSessionManager() *SessionManager

func (*SessionManager) Events

func (m *SessionManager) Events(limit int, sessionID string) []ContainerEvent

func (*SessionManager) Get

func (m *SessionManager) Get(sessionID string) (*SessionEntry, bool)

func (*SessionManager) GetOrCreate

func (m *SessionManager) GetOrCreate(ctx context.Context, sessionID string, workDir string, runtime ExecutionRuntime) (*SessionEntry, error)

func (*SessionManager) List

func (m *SessionManager) List() []SessionEntry

func (*SessionManager) RecordEvent

func (m *SessionManager) RecordEvent(event ContainerEvent)

func (*SessionManager) Stop

func (m *SessionManager) Stop(ctx context.Context, sessionID string) error

func (*SessionManager) StopAll

func (m *SessionManager) StopAll(ctx context.Context) error

type WorkspaceFS

type WorkspaceFS interface {
	ReadFile(ctx context.Context, path string) ([]byte, error)
	ReadFileRange(ctx context.Context, path string, offset, length int64) ([]byte, error)
	WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error
	Stat(ctx context.Context, path string) (fs.FileInfo, error)
	MkdirAll(ctx context.Context, path string, perm fs.FileMode) error
	Remove(ctx context.Context, path string) error
	List(ctx context.Context, path string) ([]fs.DirEntry, error)
	Mounted() bool
}

WorkspaceFS provides filesystem operations over the session workspace.

func NewBindMountedContainerFS

func NewBindMountedContainerFS() WorkspaceFS

func NewContainerFS

func NewContainerFS() WorkspaceFS

func NewCopyContainerFS

func NewCopyContainerFS() WorkspaceFS

NewCopyContainerFS is reserved for runtimes that need to move files in and out of an isolated container filesystem. The copy-based implementation is deferred until the runtime/session APIs expose the required container copy primitives.

func NewHostFS

func NewHostFS() WorkspaceFS

NewHostFS returns a WorkspaceFS backed by the local OS filesystem.