Documentation
¶
Overview ¶
Package runtime defines the interface for agent execution environments. Runtimes manage the lifecycle of the process or container that an agent runs inside. The package is UI-agnostic and MUST NOT import bubbletea, lipgloss, or anything from the tui/ package.
Index ¶
- type Backend
- type BackendCreateOpts
- type Container
- func (c *Container) Attach() error
- func (c *Container) Backend() Backend
- func (c *Container) Create(opts CreateOpts) error
- func (c *Container) Delete() error
- func (c *Container) ExecPrefix() []string
- func (c *Container) Name() string
- func (c *Container) Start() error
- func (c *Container) Status() RuntimeStatus
- func (c *Container) Stop() error
- func (c *Container) Type() string
- type CreateOpts
- type FSPolicy
- type K8sBackend
- func (b *K8sBackend) Create(name string, opts BackendCreateOpts) error
- func (b *K8sBackend) CreateAndWait(name string, opts BackendCreateOpts) (podName string, err error)
- func (b *K8sBackend) Delete(name string) error
- func (b *K8sBackend) ExecPrefix(name string) []string
- func (b *K8sBackend) IsRemote() bool
- func (b *K8sBackend) KubeClient() (kubernetes.Interface, error)
- func (b *K8sBackend) Name() string
- func (b *K8sBackend) Namespace() string
- func (b *K8sBackend) ScaleDownOne(name string) error
- func (b *K8sBackend) SetClientset(cs kubernetes.Interface)
- func (b *K8sBackend) Start(name string) error
- func (b *K8sBackend) Status(name string) (State, error)
- func (b *K8sBackend) Stop(name string) error
- type Local
- func (l *Local) Attach() error
- func (l *Local) Create(_ CreateOpts) error
- func (l *Local) Delete() error
- func (l *Local) ExecPrefix() []string
- func (l *Local) Name() string
- func (l *Local) Start() error
- func (l *Local) Status() RuntimeStatus
- func (l *Local) Stop() error
- func (l *Local) Type() string
- type NetworkPolicy
- type NetworkRule
- type OpenShellRuntime
- func (o *OpenShellRuntime) ApplyPolicy(cfg SandboxConfig) error
- func (o *OpenShellRuntime) Attach() error
- func (o *OpenShellRuntime) Create(_ CreateOpts) error
- func (o *OpenShellRuntime) CurrentPolicy() SandboxConfig
- func (o *OpenShellRuntime) Delete() error
- func (o *OpenShellRuntime) ExecPrefix() []string
- func (o *OpenShellRuntime) Name() string
- func (o *OpenShellRuntime) Start() error
- func (o *OpenShellRuntime) Status() RuntimeStatus
- func (o *OpenShellRuntime) Stop() error
- func (o *OpenShellRuntime) Type() string
- func (o *OpenShellRuntime) UpdatePolicy(cfg SandboxConfig) error
- type PodmanBackend
- func (p *PodmanBackend) Create(name string, opts BackendCreateOpts) error
- func (p *PodmanBackend) Delete(name string) error
- func (p *PodmanBackend) ExecPrefix(name string) []string
- func (p *PodmanBackend) IsRemote() bool
- func (p *PodmanBackend) Name() string
- func (p *PodmanBackend) Start(name string) error
- func (p *PodmanBackend) Status(name string) (State, error)
- func (p *PodmanBackend) Stop(name string) error
- type PolicyEnforcer
- type Resources
- type Runtime
- type RuntimeStatus
- type SandboxConfig
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend interface {
Name() string
IsRemote() bool
Create(name string, opts BackendCreateOpts) error
Start(name string) error
Stop(name string) error
Delete(name string) error
Status(name string) (State, error)
ExecPrefix(name string) []string
}
Backend is the container engine that manages container lifecycle. Podman, Docker, and Kubernetes all implement this interface.
type BackendCreateOpts ¶
type BackendCreateOpts struct {
Image string
WorkDir string
Env map[string]string
Resources *Resources
Labels map[string]string
}
BackendCreateOpts configures container creation at the backend level.
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container represents a containerized runtime environment. It delegates all lifecycle operations to a Backend (podman, docker, or kubernetes).
func NewContainer ¶
NewContainer creates a Container runtime backed by the given Backend.
func (*Container) Create ¶
func (c *Container) Create(opts CreateOpts) error
func (*Container) ExecPrefix ¶
func (*Container) Status ¶
func (c *Container) Status() RuntimeStatus
type CreateOpts ¶
type CreateOpts struct {
Name string
Image string // container image (container/openshell only)
WorkDir string // working directory to mount/use
Env map[string]string // environment variables
Resources Resources
Sandbox SandboxConfig // sandbox policy (openshell only)
}
CreateOpts carries the parameters needed to create a new runtime environment. Not all fields are relevant for every runtime type.
type FSPolicy ¶
type FSPolicy struct {
ReadOnly []string `yaml:"read_only"` // paths with read-only access
ReadWrite []string `yaml:"read_write"` // paths with read-write access
}
FSPolicy describes filesystem access rules for a sandbox.
type K8sBackend ¶
type K8sBackend struct {
// contains filtered or unexported fields
}
K8sBackend manages Kubernetes Deployments as agent execution environments. It implements the Backend interface and provides additional methods for pod-level operations (CreateAndWait, ScaleDownOne).
Thread-safe: the clientset is lazily initialized behind a mutex.
func NewK8sBackend ¶
func NewK8sBackend(namespace, kubeconfig string) *K8sBackend
NewK8sBackend creates a K8sBackend with the given namespace and kubeconfig path. If namespace is empty, it defaults to "agents". If kubeconfig is empty, in-cluster config is tried first, then default kubeconfig locations.
func (*K8sBackend) Create ¶
func (b *K8sBackend) Create(name string, opts BackendCreateOpts) error
Create ensures the deployment exists and scales it up by 1 replica. If the deployment does not exist, it is auto-created with the image and labels from opts. The deployment starts at 0 replicas and is then scaled up.
func (*K8sBackend) CreateAndWait ¶
func (b *K8sBackend) CreateAndWait(name string, opts BackendCreateOpts) (podName string, err error)
CreateAndWait creates a deployment (via Create) and then polls for up to 60 seconds until a new Running pod appears. Returns the pod name.
func (*K8sBackend) Delete ¶
func (b *K8sBackend) Delete(name string) error
Delete scales the deployment down by 1 replica (minimum 0).
func (*K8sBackend) ExecPrefix ¶
func (b *K8sBackend) ExecPrefix(name string) []string
ExecPrefix returns the kubectl exec command prefix for the named pod.
func (*K8sBackend) IsRemote ¶
func (b *K8sBackend) IsRemote() bool
IsRemote returns true; K8s workloads run on a remote cluster.
func (*K8sBackend) KubeClient ¶
func (b *K8sBackend) KubeClient() (kubernetes.Interface, error)
KubeClient returns the cached kubernetes.Interface, creating it lazily on first call. Thread-safe via mutex.
func (*K8sBackend) Namespace ¶
func (b *K8sBackend) Namespace() string
Namespace returns the configured namespace.
func (*K8sBackend) ScaleDownOne ¶
func (b *K8sBackend) ScaleDownOne(name string) error
ScaleDownOne decrements the replica count of the named deployment by 1 (minimum 0).
func (*K8sBackend) SetClientset ¶
func (b *K8sBackend) SetClientset(cs kubernetes.Interface)
SetClientset allows injecting a fake clientset for testing.
func (*K8sBackend) Start ¶
func (b *K8sBackend) Start(name string) error
Start scales the deployment up by 1 (same as Create with empty opts).
func (*K8sBackend) Status ¶
func (b *K8sBackend) Status(name string) (State, error)
Status checks the pod phase of pods belonging to the named deployment. Returns StateRunning if any pod is Running, StateCreating if pods are Pending, StateError if all pods are in error states, and StateStopped if there are no pods (replicas=0).
func (*K8sBackend) Stop ¶
func (b *K8sBackend) Stop(name string) error
Stop scales the deployment to 0 replicas.
type Local ¶
type Local struct {
// contains filtered or unexported fields
}
Local represents the default runtime where agents run as local processes. All lifecycle methods are no-ops because the agent process lifecycle is managed by spawn.Launch, not by the runtime abstraction.
func (*Local) Create ¶
func (l *Local) Create(_ CreateOpts) error
func (*Local) ExecPrefix ¶
ExecPrefix returns nil because local processes need no command prefix.
func (*Local) Status ¶
func (l *Local) Status() RuntimeStatus
Status always returns StateRunning for local processes. The actual process health is tracked by the discovery layer, not the runtime.
type NetworkPolicy ¶
type NetworkPolicy struct {
DenyAll bool `yaml:"deny_all"` // block all egress by default
Rules []NetworkRule `yaml:"rules"` // explicit allow/deny rules
Groups []string `yaml:"groups"` // named policy groups (e.g. "web-browsing")
}
NetworkPolicy defines network access rules for a sandbox.
type NetworkRule ¶
type NetworkRule struct {
Name string `yaml:"name"` // human-readable label
Hosts []string `yaml:"hosts,omitempty"` // hostnames or CIDRs
Ports []int `yaml:"ports,omitempty"` // TCP/UDP port numbers
Binaries []string `yaml:"binaries,omitempty"` // process names allowed to connect
Access string `yaml:"access"` // "allow" or "deny"
}
NetworkRule describes a single network access rule.
type OpenShellRuntime ¶
type OpenShellRuntime struct {
// contains filtered or unexported fields
}
OpenShellRuntime represents a sandboxed runtime using NVIDIA OpenShell. All lifecycle methods are stubs that return "not yet implemented" errors. The ExecPrefix method returns the real command structure so callers can plan ahead even before the runtime is fully wired.
func NewOpenShellRuntime ¶
func NewOpenShellRuntime(name, binary string) *OpenShellRuntime
NewOpenShellRuntime creates an OpenShell runtime stub. If binary is empty, it defaults to "openshell".
func (*OpenShellRuntime) ApplyPolicy ¶
func (o *OpenShellRuntime) ApplyPolicy(cfg SandboxConfig) error
func (*OpenShellRuntime) Attach ¶
func (o *OpenShellRuntime) Attach() error
func (*OpenShellRuntime) Create ¶
func (o *OpenShellRuntime) Create(_ CreateOpts) error
func (*OpenShellRuntime) CurrentPolicy ¶
func (o *OpenShellRuntime) CurrentPolicy() SandboxConfig
func (*OpenShellRuntime) Delete ¶
func (o *OpenShellRuntime) Delete() error
func (*OpenShellRuntime) ExecPrefix ¶
func (o *OpenShellRuntime) ExecPrefix() []string
ExecPrefix returns the real OpenShell exec command structure even though the runtime itself is not yet implemented. This allows the spawn layer to prepare the correct command shape.
func (*OpenShellRuntime) Name ¶
func (o *OpenShellRuntime) Name() string
func (*OpenShellRuntime) Start ¶
func (o *OpenShellRuntime) Start() error
func (*OpenShellRuntime) Status ¶
func (o *OpenShellRuntime) Status() RuntimeStatus
func (*OpenShellRuntime) Stop ¶
func (o *OpenShellRuntime) Stop() error
func (*OpenShellRuntime) Type ¶
func (o *OpenShellRuntime) Type() string
func (*OpenShellRuntime) UpdatePolicy ¶
func (o *OpenShellRuntime) UpdatePolicy(cfg SandboxConfig) error
type PodmanBackend ¶
type PodmanBackend struct {
// contains filtered or unexported fields
}
PodmanBackend implements Backend for local container engines (podman or docker).
func NewPodmanBackend ¶
func NewPodmanBackend(engine string) *PodmanBackend
NewPodmanBackend creates a backend for podman or docker. Empty engine defaults to "podman".
func (*PodmanBackend) Create ¶
func (p *PodmanBackend) Create(name string, opts BackendCreateOpts) error
func (*PodmanBackend) Delete ¶
func (p *PodmanBackend) Delete(name string) error
func (*PodmanBackend) ExecPrefix ¶
func (p *PodmanBackend) ExecPrefix(name string) []string
func (*PodmanBackend) IsRemote ¶
func (p *PodmanBackend) IsRemote() bool
func (*PodmanBackend) Name ¶
func (p *PodmanBackend) Name() string
func (*PodmanBackend) Start ¶
func (p *PodmanBackend) Start(name string) error
func (*PodmanBackend) Stop ¶
func (p *PodmanBackend) Stop(name string) error
type PolicyEnforcer ¶
type PolicyEnforcer interface {
// ApplyPolicy configures the sandbox with the given policy and
// restarts enforcement.
ApplyPolicy(cfg SandboxConfig) error
// UpdatePolicy merges new rules into the running policy without a
// full restart.
UpdatePolicy(cfg SandboxConfig) error
// CurrentPolicy returns the active sandbox configuration.
CurrentPolicy() SandboxConfig
}
PolicyEnforcer is implemented by runtimes that support sandboxing with network and filesystem access control. Currently only the OpenShell runtime implements this interface.
type Resources ¶
type Resources struct {
CPULimit string // e.g. "2" or "500m"
MemoryLimit string // e.g. "4Gi" or "512Mi"
}
Resources specifies compute limits for a runtime environment.
type Runtime ¶
type Runtime interface {
// Type returns a short identifier: "local", "container", "openshell".
Type() string
// Name returns the instance name of this runtime.
Name() string
// Create provisions the runtime environment (pull image, create
// container, etc.). A no-op for local runtimes.
Create(opts CreateOpts) error
// Start begins execution inside the runtime. A no-op for local
// runtimes (the agent process IS the runtime).
Start() error
// Stop halts the runtime without destroying it.
Stop() error
// Delete removes the runtime and cleans up resources.
Delete() error
// Status returns the current lifecycle state.
Status() RuntimeStatus
// ExecPrefix returns the command prefix needed to execute a command
// inside this runtime. For local runtimes this is nil (no prefix).
// For containers it might be ["podman", "exec", "-it", "name"].
ExecPrefix() []string
// Attach connects the caller's terminal to the runtime. For local
// runtimes this is a no-op. For containers it may exec into the
// container interactively.
Attach() error
}
Runtime is the interface that all execution environments implement. Local processes, containers, and sandboxed runtimes all satisfy this contract so the rest of aimux can treat them uniformly.
type RuntimeStatus ¶
RuntimeStatus holds the current state plus an optional human-readable message (e.g. an error string when State == StateError).
type SandboxConfig ¶
type SandboxConfig struct {
Type string `yaml:"type"` // "openshell", "gvisor", etc.
Network NetworkPolicy `yaml:"network"`
Filesystem FSPolicy `yaml:"filesystem"`
}
SandboxConfig describes the security policy for a sandboxed runtime.
func (SandboxConfig) HasNetworkPolicy ¶
func (s SandboxConfig) HasNetworkPolicy() bool
HasNetworkPolicy returns true if any network restrictions are configured.