Getting started
Deploy the operator once, then request workspace environments from your main Paseo daemon.
Requirements
- Kubernetes 1.32+ with dynamic PVC provisioning.
- Paseo 0.15.3+ on your main daemon and workspace daemons.
- Your main daemon can resolve and reach cluster Service addresses. Running it in the cluster is the simplest setup.
kubectlon the main daemon, with access to the managed namespace.- Docker for image builds; Node 22+ for plugin development.
Build your images
Clone the repository. Replace your-registry with a registry your cluster can pull from.
git clone https://github.com/lerenn/paseo-kubernetes-workspaces.git
cd paseo-kubernetes-workspaces
docker build -t your-registry/paseo-workspaces-operator:0.1.0 .
docker build -t your-registry/paseo-workspace:0.16.2 images/workspace
docker push your-registry/paseo-workspaces-operator:0.1.0
docker push your-registry/paseo-workspace:0.16.2
The base workspace image contains Paseo and basic development utilities. Install your agent provider executables in a derived image and inject their credentials through a Kubernetes Secret.
Deploy the operator
Set the operator image in config/operator.yaml to the image you just pushed, then apply the manifests.
kubectl apply -f config/crd.yaml
kubectl apply -f config/operator.yaml
# Optional: cap aggregate workspace resources.
kubectl apply -f config/quota.yaml
Configure the main daemon
Set these variables in the environment of the main daemon, then restart it. Shell exports in a separate terminal do not change an already running daemon.
PASEO_WORKSPACE_IMAGE=your-registry/paseo-workspace:0.16.2
PASEO_WORKSPACE_NAMESPACE=paseo-workspaces
PASEO_WORKSPACE_CLUSTER_ID=my-cluster
# Optional: reverse registration for messages back to the main daemon.
PASEO_MAIN_CONNECTION=main-daemon.paseo-workspaces.svc:6767
# Optional: inject credentials into workspace pods.
PASEO_WORKSPACE_SECRET=workspace-credentials
Apply config/plugin-rbac.yaml and bind its Role to the main daemon’s ServiceAccount. Alternatively, grant equivalent access through its kubeconfig. The main daemon needs permission to get, list, create, patch and delete PaseoWorkspace resources.
Enable plugins in Paseo settings and install the companion from the cloned checkout:
cd plugin
npm ci
npm run typecheck
paseo plugin install "$PWD"
Start your first workspace
- Open a new agent session so it receives the companion’s tools.
- Call
kubernetes_workspace_create({ "name": "demo" }). - Poll
kubernetes_workspace_list({})until the environment’shostStatusisonline. - Use the returned
serverIdwith Paseo’s cross-host tools. Create a Paseo workspace at/workspaceon that daemon, then start agents there. - Export results, then call
kubernetes_workspace_release({ "name": "demo" }).
Delete if physical storage should also be removed.Check an environment
kubectl -n paseo-workspaces get pw
kubectl -n paseo-workspaces describe pod pw-demo
kubectl -n paseo-workspaces logs pw-demo
A Ready pod is not necessarily a connected host. Check the companion’s hostStatus and error fields for registration problems. Configure daemon authentication and network policy for your cluster; an optional policy is provided in config/network-policy.yaml.
See the reference for all configuration options.