Documentation
¶
Overview ¶
Package sandbox defines the pluggable sandbox runtime interface for executing MCP server plugins in isolated environments. Backends include Docker/Podman (standalone) and Kubernetes (cluster deployments).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DockerRuntime ¶
type DockerRuntime struct{}
DockerRuntime implements Runtime using Docker (or Podman) containers. Each sandbox is a `docker run -i --rm` invocation whose stdin/stdout carry the MCP stdio transport.
func NewDockerRuntime ¶
func NewDockerRuntime() (*DockerRuntime, error)
NewDockerRuntime creates a DockerRuntime. Returns an error if the Docker CLI is not found on PATH.
func (*DockerRuntime) Close ¶
func (d *DockerRuntime) Close() error
Close is a no-op for Docker — there are no persistent runtime resources.
type KubernetesConfig ¶
type KubernetesConfig struct {
Namespace string // K8s namespace for sandbox Pods (default: "denkeeper-sandboxes")
Kubeconfig string // path to kubeconfig; empty = in-cluster
RuntimeClass string // optional RuntimeClassName (e.g. "gvisor", "kata")
}
KubernetesConfig holds the settings for the Kubernetes sandbox runtime.
type KubernetesRuntime ¶
type KubernetesRuntime struct {
// contains filtered or unexported fields
}
KubernetesRuntime implements Runtime by creating ephemeral Pods in a Kubernetes cluster. Each sandbox is a Pod whose stdin/stdout are connected via `kubectl exec -i`.
func NewKubernetesRuntime ¶
func NewKubernetesRuntime(cfg KubernetesConfig, logger *slog.Logger) (*KubernetesRuntime, error)
NewKubernetesRuntime creates a KubernetesRuntime. It verifies that kubectl is on PATH, builds a Kubernetes client from the config, and ensures the sandbox namespace exists with the correct PSA labels.
func (*KubernetesRuntime) Close ¶
func (k *KubernetesRuntime) Close() error
Close deletes all tracked sandbox Pods. Best-effort: logs errors but does not stop on the first failure.
func (*KubernetesRuntime) Spawn ¶
func (k *KubernetesRuntime) Spawn(ctx context.Context, name string, opts SpawnOpts) (*Process, error)
Spawn creates an ephemeral Pod for the given plugin and returns connection info for kubectl exec. If a pod with the same name already exists (e.g. from a previous crash), it is deleted first.
type NetworkPolicy ¶
type NetworkPolicy string
NetworkPolicy controls the network access level for a sandbox.
const ( NetworkNone NetworkPolicy = "none" // no network access NetworkEgress NetworkPolicy = "egress" // outbound only NetworkFull NetworkPolicy = "full" // unrestricted )
type Process ¶
type Process struct {
Command string // executable (e.g. "docker", "kubectl")
Args []string // arguments
Env map[string]string // additional env vars (nil if baked into args)
}
Process describes how to connect to a spawned sandbox's stdin/stdout for MCP stdio transport. The caller execs Command with Args and communicates over the process's stdio pipes.
type Runtime ¶
type Runtime interface {
// Spawn creates a sandboxed environment and returns connection info.
// The returned Process describes the command to exec for MCP stdio.
// name is a unique identifier for the sandbox (typically the plugin name).
Spawn(ctx context.Context, name string, opts SpawnOpts) (*Process, error)
// Stop tears down the sandbox identified by name. For Docker this is a
// no-op (--rm handles cleanup). For Kubernetes this deletes the Pod.
Stop(ctx context.Context, name string) error
// Close releases all runtime resources and stops any active sandboxes.
Close() error
}
Runtime is the interface for sandbox backends that can spawn isolated environments for MCP server plugins. Each backend implements the same lifecycle: spawn a sandbox, return connection info, and tear down on stop.
type SpawnOpts ¶
type SpawnOpts struct {
Image string // OCI image to run
Command string // entrypoint override (empty = image default)
Args []string // arguments passed to the entrypoint
Env map[string]string // environment variables
MemoryLimit string // memory limit (e.g. "256m", "1g")
CPULimit string // CPU limit (e.g. "0.5", "2")
Network NetworkPolicy // network access level
Volumes []string // bind mounts ("host:container[:ro]")
}
SpawnOpts describes the sandboxed environment to create for a plugin.
Source Files