runtime

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Jun 6, 2026 License: MIT Imports: 15 Imported by: 0

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

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

func NewContainer(name string, backend Backend) *Container

NewContainer creates a Container runtime backed by the given Backend.

func (*Container) Attach

func (c *Container) Attach() error

func (*Container) Backend

func (c *Container) Backend() Backend

Backend returns the underlying backend.

func (*Container) Create

func (c *Container) Create(opts CreateOpts) error

func (*Container) Delete

func (c *Container) Delete() error

func (*Container) ExecPrefix

func (c *Container) ExecPrefix() []string

func (*Container) Name

func (c *Container) Name() string

func (*Container) Start

func (c *Container) Start() error

func (*Container) Status

func (c *Container) Status() RuntimeStatus

func (*Container) Stop

func (c *Container) Stop() error

func (*Container) Type

func (c *Container) Type() string

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) Name

func (b *K8sBackend) Name() string

Name returns "kubernetes".

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 NewLocal

func NewLocal(name string) *Local

NewLocal creates a Local runtime with the given instance name.

func (*Local) Attach

func (l *Local) Attach() error

Attach is a no-op for local runtimes.

func (*Local) Create

func (l *Local) Create(_ CreateOpts) error

func (*Local) Delete

func (l *Local) Delete() error

func (*Local) ExecPrefix

func (l *Local) ExecPrefix() []string

ExecPrefix returns nil because local processes need no command prefix.

func (*Local) Name

func (l *Local) Name() string

func (*Local) Start

func (l *Local) Start() error

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.

func (*Local) Stop

func (l *Local) Stop() error

func (*Local) Type

func (l *Local) Type() string

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) Status

func (p *PodmanBackend) Status(name string) (State, 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

type RuntimeStatus struct {
	State   State
	Message string
}

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.

type State

type State int

State represents the lifecycle state of a runtime environment.

const (
	StateStopped  State = iota // not running
	StateCreating              // being provisioned
	StateRunning               // active and healthy
	StateError                 // failed or unhealthy
)

func (State) String

func (s State) String() string

String returns a human-readable label for the state.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL