Docs · Start here
Architecture.
How Remoco works and what the terms mean. A Remoco 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
Remoco 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.