Sas Swart
5b6b7719df
## Problem When a prebuilt workspace is claimed, the agent reinitializes via a single fire-and-forget pubsub event over SSE. If the agent's SSE connection is interrupted at claim time, the event is permanently lost — the workspace is stuck with no self-healing path. Additionally, regular (non-prebuild) workspaces had no way to opt out of the `/reinit` polling loop — agents would reconnect indefinitely to an endpoint that would never send them anything useful. ## Root Cause `workspaceAgentReinit` fetches the workspace (with its current `owner_id`) via `GetWorkspaceByAgentID`, but never checked whether a claim already happened. It only subscribed to pubsub for future events. The database already has durable claim state (`owner_id` changes from `PrebuildsSystemUserID` to the real user), but no layer ever consulted it on reconnection. ## Solution ### Server-side durable check with first-build-initiator gating **TOCTOU-safe ordering**: Subscribe to pubsub claim events *before* any durable checks, so a claim that fires during the check is buffered in the channel rather than lost. **First-build-initiator gating**: When `!workspace.IsPrebuild()` (owner is no longer the system user), look up the first build's `InitiatorID`. The prebuild reconciler always uses `PrebuildsSystemUserID` as the initiator. This distinguishes claimed prebuilds from regular workspaces without any SQL schema changes. - **Regular workspace** (first build initiator ≠ system user) → **409 Conflict**, agent stops reconnecting - **Claimed prebuild, build completed** → pre-seed channel with reinit event and close it, transmitter delivers one-shot then exits - **Claimed prebuild, build in-progress** → fall through to pubsub subscription, agent waits for completion event - **Unclaimed prebuild** → pubsub subscription (existing happy path) ### Declarative reinit events (defense-in-depth) - Added `UserID` field to `ReinitializationEvent` with JSON tags - Switched pubsub serialization from raw string to JSON (with backward-compat fallback for rolling upgrades) - Populated `UserID` at both the publish site and the durable check ### Agent SDK: 409 handling `WaitForReinitLoop` detects 409 Conflict from the server and closes the `reinitEvents` channel, cleanly exiting the retry goroutine. ### Agent CLI: fixed two bugs + added reinitCtx - **Closed channel (`!ok`)**: now blocks on `<-ctx.Done()` instead of `continue`, keeping the current agent running. Previously this would leak agents by skipping `agnt.Close()` and re-entering the loop. - **Duplicate owner reinit**: cancels `reinitCtx` (stops the reinit goroutine), then blocks on `<-ctx.Done()`. Previously `continue` would skip cleanup and create a new agent on the next loop iteration. - **`reinitCtx`**: a cancellable child of `ctx` passed to `WaitForReinitLoop`, allowing the agent to stop the reinit HTTP polling after reinit completes. ### Agent-side idempotency Tracks `lastOwnerID` in the agent reinit loop — duplicate events for the same owner are skipped. ## Testing - **"unclaimed prebuild receives reinit via pubsub"**: prebuild owned by system user, pubsub event triggers reinit - **"claimed prebuild receives one-shot reinit on reconnect"**: first build by system user, owner changed, build completed → immediate reinit (no pubsub needed) - **"claimed prebuild waits during in-progress claim build"**: claimed but build still running → no reinit until build completes - **"regular workspace gets 409"**: first build by real user → 409 Conflict, agent stops polling - Updated claim publisher/listener tests: verify `UserID` survives JSON round-trip + backward compat with raw string payloads - Updated SSE round-trip test: verify `UserID` survives transmit → receive cycle Fixes #22359 ## Rolling upgrade note During a rolling deploy where old coderd instances coexist with new ones, the pubsub `ReinitializationEvent` has a new `workspace_id` field (JSON key `workspace_id`). Old publishers send a raw reason string instead of JSON; the new listener gracefully falls back by treating the entire payload as the reason and filling in `WorkspaceID` from context. The only visible effect during the upgrade window is that `WorkspaceID` may be the zero UUID in agent-side logs — this is cosmetic and resolves once all instances are updated.
About
Coder is a self-hosted, open source, cloud development environment that works with any cloud, IDE, OS, Git provider, and IDP.
Screenshots of Coder workspaces and connections
Coder is built on common development interfaces and infrastructure tools to make the process of provisioning and accessing remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity.
IDE support
You can use:
-
Any Web IDE, such as
- code-server
- JetBrains Projector
- Jupyter
- And others
-
Your existing remote development environment:
-
A file sync such as Mutagen
Why remote development
Remote development offers several benefits for users and administrators, including:
-
Increased speed
- Server-grade cloud hardware speeds up operations in software development, from loading the IDE to compiling and building code, and running large workloads such as those for monolith or microservice applications.
-
Easier environment management
- Built-in infrastructure tools such as Terraform, nix, Docker, Dev Containers, and others make it easier to onboard developers with consistent environments.
-
Increased security
- Centralize source code and other data onto private servers or cloud services instead of local developers' machines.
- Manage users and groups with SSO and Role-based access controlled (RBAC).
-
Improved compatibility
- Remote workspaces can share infrastructure configurations with other development, staging, and production environments, reducing configuration drift.
-
Improved accessibility
- Connect to remote workspaces via browser-based IDEs or remote IDE extensions to enable developers regardless of the device they use, whether it's their main device, a lightweight laptop, Chromebook, or iPad.
Read more about why organizations and engineers are moving to remote development on our blog, the Slack engineering blog, or from OpenFaaS's Alex Ellis.
Why Coder
The key difference between Coder and other remote IDE platforms is the added layer of infrastructure control. This additional layer allows admins to:
- Simultaneously support ARM, Windows, Linux, and macOS workspaces.
- Modify pod/container specs, such as adding disks, managing network policies, or setting/updating environment variables.
- Use VM or dedicated workspaces, developing with Kernel features (no container knowledge required).
- Enable persistent workspaces, which are like local machines, but faster and hosted by a cloud service.
How much does it cost?
Coder is free and open source under GNU Affero General Public License v3.0. All developer productivity features are included in the Open Source version of Coder. A Premium license is available for enhanced support options and custom deployments.
How does Coder work
Coder workspaces are represented with Terraform, but you don't need to know Terraform to get started. We have a database of production-ready templates for use with AWS EC2, Azure, Google Cloud, Kubernetes, and more.
Providers and compute environments
Coder workspaces can be used for more than just compute. You can use Terraform to add storage buckets, secrets, sidecars, and more.
Visit the templates documentation to learn more.
What Coder is not
-
Coder is not an infrastructure as code (IaC) platform.
- Terraform is the first IaC provisioner in Coder, allowing Coder admins to define Terraform resources as Coder workspaces.
-
Coder is not a DevOps/CI platform.
- Coder workspaces can be configured to follow best practices for cloud-service-based workloads, but Coder is not responsible for how you define or deploy the software you write.
-
Coder is not an online IDE.
- Coder supports common editors, such as VS Code, vim, and JetBrains, all over HTTPS or SSH.
-
Coder is not a collaboration platform.
- You can use Git with your favorite Git platform and dedicated IDE extensions for pull requests, code reviews, and pair programming.
-
Coder is not a SaaS/fully-managed offering.
- Coder is a self-hosted solution. You must host Coder in a private data center or on a cloud service, such as AWS, Azure, or GCP.
Using Coder v1?
If you're a Coder v1 customer, view the v1 documentation or the v2 migration guide and FAQ.
Up next
- Template
- Installing Coder
- Quickstart to try Coder out for yourself.