Kubernetes Workspaces

How it works

Kubernetes manages the execution environments. Existing Paseo daemons manage the work inside them.

Two components, distinct responsibilities

ComponentOwns
Go operatorReconciliation of pods, Services, PVCs and readiness status.
Main-daemon companionEnvironment requests, host registration and registration cleanup.
Workspace Paseo daemonIts agents, conversations, provider execution, terminals and files.

From request to execution

  1. The companion applies a PaseoWorkspace. Its stable name makes identical requests idempotent.
  2. The operator creates pw-<name>: one pod, one ClusterIP Service on port 6767 and one PVC mounted at /workspace.
  3. The pod runs paseo daemon run. Its daemon home is /workspace/.paseo, keeping its identity and local state on persistent storage.
  4. A TCP readiness probe marks the pod Ready. The companion registers its Service endpoint through paseo.hosts.add.
  5. Once the connected host is online, agents use its serverId with Paseo’s existing cross-host tools.

Communication in both directions

Registering a workspace daemon on the main daemon gives the main daemon access to that host. It does not automatically grant reverse access.

When PASEO_MAIN_CONNECTION is set, the companion uses the online remote host API to register the main daemon there too. The main endpoint must be reachable from the pod, with appropriate authentication. Pod agents can then discover the main host and use its agent tools.

Reconciliation and recovery

The operator recreates missing child resources. A replacement pod reuses the existing PVC. Owner checks prevent adoption of unrelated resources with a conflicting name.

Host reconciliation runs on list/create calls and every five seconds after the first companion interaction or agent session open. After a plugin restart, opening a session or listing environments resumes the loop. Concurrent inventory syncs share one request.

Registrations use a source key based on cluster, namespace and resource UID. Repeating an unchanged registration preserves a user’s disabled-host choice. Cleanup runs only after a successful Kubernetes inventory read, so an API outage does not erase saved hosts.

Resource boundaries

CPU limits throttle busy environments; memory overages can cause OOM termination. Ephemeral storage limits cover the container’s temporary disk usage. Persistent storage capacity and reclamation depend on your storage provisioner.

The optional ResourceQuota caps aggregate admission. When quota is exhausted, Kubernetes rejects new resources and the operator retries with backoff. This is not a fair scheduling queue, and a PVC can exist while its pod waits for capacity.

Workspace pods run as a non-root user, drop Linux capabilities and do not receive a mounted Kubernetes ServiceAccount token. Adapt the optional network policy and configure daemon authentication for your deployment.

Cleanup

Release deletes the custom resource. Kubernetes owner references garbage-collect its pod, Service and PVC. Subsequent companion reconciliation removes the saved host registration.

Export results before release. PVC deletion is destructive; physical volume deletion follows the StorageClass reclaim policy.

Current scope

For the implementation decision, see the architecture document.