Sandbox worker
oma-bridge-daemon
Outbound reverse-WebSocket worker. Pairs with a remote control plane (e.g. hosted app.oma.duyet.net). No ServiceAccount, RBAC, Service, or Ingress — the pod only dials out.
provider: subprocess · openshell
Features / Private Kubernetes
Connect your private Kubernetes cluster
Keep the control plane on OMA (hosted or self-host). Put sandbox compute on a cluster you already operate — your VPC, images, node pools, and NetworkPolicy. One Helm chart wires the path; each session provisions a pod (or OpenShell sandbox) on that cluster.
Why private K8s
- Data residency: tools run inside your cluster boundary — not a vendor micro-VM you don't control.
- Same agents:
swap only
sandbox_provideron the environment. - Helm-native: three charts for bridge worker, HTTP gateway, or full control plane.
How it fits
Sessions, history, vault credentials, and the model loop stay on the control plane. The cluster only runs sandbox work. Pick the path that matches how your plane reaches the cluster.
Three Helm charts
HTTP gateway
oma-k8s-bridge
Token-gated REST bridge so a Cloudflare Worker can create/exec/destroy
sandboxes without native k8s clients. Backs
k8s-remote and
openshell.
secrets: K8S_SANDBOX_GATEWAY_URL
Full plane
oma
Self-host the entire control plane on the cluster — API, Console, vault sidecar, optional agent-sandbox CRD hook. Use when you want zero dependency on a remote plane.
provider: k8s · in-cluster
Install the bridge worker
Most common path: keep the hosted control plane, put sandboxes on your private cluster. Pair once, ship credentials as a Secret, Helm install.
pair + secret
# 1. Pair once (browser OAuth or pairing code)
$ oma bridge setup --server-url=https://app.oma.duyet.net --no-service
# 2. Ship creds into the cluster (never on the Helm CLI)
$ kubectl -n oma create secret generic oma-bridge-daemon-creds \
--from-file=credentials.json=$HOME/.oma/bridge/credentials.json \
--from-file=machine-id=$HOME/.oma/bridge/machine-id helm install
$ helm dependency build ./charts/oma-bridge-daemon
$ helm install oma-bridge ./charts/oma-bridge-daemon \
--namespace oma --create-namespace \
--set secret.existingSecret=oma-bridge-daemon-creds
✓ Deployment/oma-bridge-daemon 1/1 Running
# runtime appears on Console → Runtimes environment.json · point sessions at the cluster
{
"name": "homelab-k8s",
"config": {
"type": "cloud",
"sandbox_provider": "subprocess",
"packages": { "pip": ["numpy"] }
}
}
For Cloudflare-native k8s-remote, install
oma-k8s-bridge, set
K8S_SANDBOX_GATEWAY_URL, and use
sandbox_provider: "k8s-remote". Full comparison:
k8s-remote vs openshell.
Cluster vs laptop vs full self-host
| Path | Where tools run | Control plane | Install |
|---|---|---|---|
| Private Kubernetes | Pods / OpenShell on your cluster | Hosted or remote | helm install … |
| Local machine | Your laptop / workstation | Hosted or remote | oma bridge setup |
| Full OMA on K8s | Same cluster (or wherever you point it) | In-cluster main-node | charts/oma |
FAQ
Do I have to open inbound ports on my cluster?
Not with the bridge daemon path. oma-bridge-daemon only dials out over WebSocket to the control plane — same outbound-only model as a laptop bridge. The k8s-bridge path is an HTTP service you expose (or keep private with a tunnel) so a Cloudflare Worker can reach it; that one is intentionally network-reachable by the control plane.
Which Helm chart should I install?
Want sandboxes on your cluster while keeping hosted app.oma.duyet.net (or another OMA) as the control plane? Install oma-bridge-daemon (outbound) or oma-k8s-bridge (HTTP for Cloudflare / k8s-remote / openshell). Want the entire control plane on the cluster too? Install the full oma chart instead.
How does a session pick my cluster?
Create an environment with config.sandbox_provider set to subprocess (paired bridge runtime), k8s-remote, openshell, or k8s on self-host Node. Sessions that use that environment provision sandboxes on the connected cluster — agent config stays the same.
Can I use my own images, node pools, and NetworkPolicy?
Yes on the k8s-remote / in-cluster path: sandboxes are ordinary pods (Sandbox CRDs) under your RBAC and policy. OpenShell is the alternative when you want managed microVM isolation and SandboxPolicy egress instead of raw pods.
What are the current limitations?
Memory-store and session-outputs bind-mounts are not available over the HTTP tar / bridge APIs (same as boxrun). Pair a machine or run the full Node path when you need those mounts. Always fail-loud: if the bridge is offline, the first sandbox op surfaces session.error rather than hanging.