Reference
The companion requests execution environments. The operator manages their Kubernetes resources.
Agent tools
| Tool | Input | Behavior |
|---|---|---|
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
| Variable | Default | Purpose |
|---|---|---|
PASEO_WORKSPACE_IMAGE | Required | Image used by the companion for new environments. |
PASEO_WORKSPACE_NAMESPACE | paseo-workspaces | Namespace used by kubectl. |
PASEO_WORKSPACE_CLUSTER_ID | default | Stable cluster scope for host registration ownership. |
PASEO_WORKSPACE_SECRET | Unset | Existing Secret whose keys become workspace container environment variables. |
PASEO_MAIN_CONNECTION | Unset | Reachable 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 field | Default / requirement |
|---|---|
image | Required container image. |
command | ["paseo", "daemon", "run"] |
storage | 10Gi; a positive whole quantity in Mi, Gi or Ti. |
storageClassName | Cluster’s default StorageClass. |
secretName | Optional Secret in the same namespace, injected with envFrom. |
resources | Requests 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
config/crd.yaml— custom resource schema.config/operator.yaml— namespace, permissions and operator Deployment.config/plugin-rbac.yaml— Role for the main daemon; add a binding for your ServiceAccount.config/example.yaml— sample workspace resource.config/quota.yaml— optional aggregate capacity limits.config/network-policy.yaml— optional ingress policy for a labeled main daemon in the same namespace.