Kubernetes Workspaces

Reference

The companion requests execution environments. The operator manages their Kubernetes resources.

Agent tools

ToolInputBehavior
kubernetes_workspace_create{"name":"demo"}Idempotently applies a workspace resource and returns the environment list. It does not wait for a usable host.
kubernetes_workspace_list{}Lists environments and reconciles forward and optional reverse registrations.
kubernetes_workspace_release{"name":"demo"}Requests deletion without waiting for cleanup. Missing resources are ignored.

Names are 1–50 characters: lowercase letters, digits and hyphens, starting and ending with a letter or digit.

List results

Each entry includes name, phase, serverId, hostStatus and error. Before registration, host fields can be null. Use serverId only after hostStatus becomes online.

Plugin RPCs

The equivalent RPCs are environment.create, environment.list and environment.release. Contracts live in plugin/shared/contracts.ts.

Main-daemon environment

VariableDefaultPurpose
PASEO_WORKSPACE_IMAGERequiredImage used by the companion for new environments.
PASEO_WORKSPACE_NAMESPACEpaseo-workspacesNamespace used by kubectl.
PASEO_WORKSPACE_CLUSTER_IDdefaultStable cluster scope for host registration ownership.
PASEO_WORKSPACE_SECRETUnsetExisting Secret whose keys become workspace container environment variables.
PASEO_MAIN_CONNECTIONUnsetReachable main-daemon connection target for reverse registration.

PaseoWorkspace

API: workspaces.paseo.sh/v1alpha1. Kind: PaseoWorkspace. Short name: pw. One resource creates one execution environment.

apiVersion: workspaces.paseo.sh/v1alpha1
kind: PaseoWorkspace
metadata:
  name: demo
  namespace: paseo-workspaces
spec:
  image: your-registry/paseo-workspace:0.16.2
  storage: 10Gi
  resources:
    requests: {cpu: 250m, memory: 512Mi, ephemeral-storage: 1Gi}
    limits: {cpu: '2', memory: 4Gi, ephemeral-storage: 4Gi}
Spec fieldDefault / requirement
imageRequired container image.
command["paseo", "daemon", "run"]
storage10Gi; a positive whole quantity in Mi, Gi or Ti.
storageClassNameCluster’s default StorageClass.
secretNameOptional Secret in the same namespace, injected with envFrom.
resourcesRequests and limits above; explicit resources must include CPU, memory and ephemeral storage in both maps.

The entire spec is immutable. Create a new environment to change it. To customize resources or storage beyond the companion’s defaults, create the resource directly, then list environments through the companion to register it.

Status

The operator reports phase (Pending, Ready or Failed), a Service endpoint, and observedGeneration. The companion also reports Deleting when deletion has been requested.

Operator options

--namespace selects the managed namespace; the executable defaults to default, and the supplied Deployment sets paseo-workspaces. Leader election runs in that namespace. The operator’s Role is namespace-scoped.

Provided manifests