Docs · Start here
Architecture.
How DOSS Cloud works and what the terms mean. A DOSS Cloud is a managed cloud workstation; pods group related workstations for a team or workload; clusters are the regional infrastructure boundary; a fleet is everything you run across clusters.
Taxonomy
Borrowed loosely from Kubernetes, scaled up a level — a "remoco" is a whole VM, not a container.
remoco · one workstation
One persistent VM. Boots in seconds from a golden image, keeps a /home/user disk across suspend/resume, runs your agent and your dev servers in tmux. Each remoco has a stable identity (<shortname>) that shows up in URLs: <branch>.<service>.<shortname>.remoco.dev.
pod · a group of remocos
A team's remocos, or a workload's fleet of agents. Pods share config (class, image, network policy, access control) and are the scheduling unit for "give my 10 engineers a remoco" or "spin up 20 CI runners for this workload." Internally, a pod maps one-to-one with a Cloud Workstations WorkstationConfig.
cluster · regional infrastructure
A regional boundary (us-central1, europe-west1, etc.) that holds pods. One cluster per region per org. Networking, VPC peering, and the tunnel that terminates *.remoco.dev traffic all live here. Maps one-to-one to a Cloud Workstations WorkstationCluster.
fleet · everything you run
Your organization's full view across clusters. The /fleet endpoint and the HUD in the hero return this. Pricing and billing roll up at fleet scope.
Where the pieces live
DOSS Cloud runs in your infrastructure (GCP today, AWS + self-host later). DOSS Labs operates the control plane and sells the unit economics; you get root on every remoco.
| Layer | What | Where it runs |
|---|---|---|
| Your agent | Claude Code, Codex, Cursor, DOSSBOT, or custom harness | Your mac / CI / own service |
| Control plane | HTTP API (api.remoco.dev) + Postgres + billing | DOSS-operated, Cloud Run |
| Tunnel | Cloudflared named tunnel per cluster + CF Access policies | Cloud-side (Cloudflare) |
| Cluster | GCP WorkstationCluster (regional) | Your GCP project (or DOSS's) |
| Pod | GCP WorkstationConfig (image, class, idle-timeout) | Inside the cluster |
| remoco | GCP Workstation (the VM, persistent disk, dev servers) | Inside the pod |
Request path
What happens when your browser hits main.web.wiley.remoco.dev:
- DNS resolves to Cloudflare's anycast edge (CNAME to the named tunnel).
- Cloudflare Access checks the request against the policy for that hostname (public, team, or specific user). 403s unauthenticated traffic for private URLs.
- Cloudflared tunnel ingests the request and hands it to the remoco's local remoco-proxy daemon on
:8081. - remoco-proxy dispatches by Host header to the right dev server port (e.g.
:3333for Next.js,:3000for Vite), and injects the debugger overlay script + favicon. - Response streams back through the tunnel to the browser.
Persistence & identity
- User identity: WorkOS SSO (v0.2) gives you a workspace-scoped JWT. The control plane verifies, issues per-user capability tokens for remoco operations.
- Workstation state: Postgres (
workstations,exposes,artifactstables) is authoritative.gcloudis the fallback for reconciliation. - Home disk:
/home/usersurvives suspend / resume / image bumps. Your dotfiles, clones, and long-running data persist. - Idle suspend: remocos stop after 6h of no client connection (tunable per pod). Resume is ~10s from stopped.
Failure domains
What dies with what, worst case:
- One remoco crashes → just that one is affected. Other remocos in the pod keep running. Resume or recreate in seconds.
- Tunnel dies → the remoco is still up, but external URLs (
*.remoco.dev) return Cloudflare 502 until the tunnel comes back. SSH keeps working. - Pod config breaks (e.g. bad image tag) → new remocos in that pod won't start, existing ones continue running until suspended.
- Cluster goes down → regional outage. Another region keeps going; fleet view still reflects reality elsewhere.
- Control plane down → you can't provision new remocos or mutate state via the API, but existing remocos keep working. Local CLI operations (
remoco dev, SSH, tunnel ingress) are unaffected.