Files
coder/docs/user-guides/workspace-lifecycle.md
T
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00

5.9 KiB

title
title
Workspace lifecycle

Workspaces are flexible, reproducible, and isolated units of compute. Workspaces are created via Terraform, managed through the Coder control plane, accessed through the Coder agent, then stopped and deleted again by Terraform.

This page covers how workspaces move through this lifecycle. To learn about automating workspace schedules for cost control, read the workspace scheduling docs.

Workspace ephemerality

Workspaces are composed of resources which may be ephemeral or persistent. Persistent resources stay provisioned when the workspace is stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.

Template administrators can learn more about resource configuration in the extending templates docs.

Workspace States

Generally, there are 3 states that a workspace may fall into:

  • Running: Started and ready for connections
  • Stopped: Ephemeral resources destroyed, persistent resources idle
  • Deleted: All resources destroyed, workspace records removed from database

If some error occurs during the above, a workspace may fall into one of the following broken states:

  • Failed: Failure during provisioning, no resource consumption
  • Unhealthy: Resources have been provisioned, but the agent can't facilitate connections

Workspace creation

Workspaces are created from templates via the CLI, API, or dashboard.

By default, there is no limit on the number of workspaces a user may create, regardless of the template's resource demands. Enterprise administrators may limit the number of workspaces per template, group, and organization using quotas to prevent over provisioning and control costs.

When a user creates a workspace, they're sending a build request to the control plane. Coder takes this and uses Terraform to provision a workspace defined by your template. Generally, templates define the resources and environment of a workspace.

The resources that run the agent are described as computational resources, while those that don't are called peripheral resources. A workspace must contain some computational resource to run the Coder agent process.

The provisioned workspace's computational resources start the agent process, which opens connections to your workspace via SSH, the terminal, and IDES such as JetBrains or VSCode.

Once started, the Coder agent is responsible for running your workspace startup scripts. These may configure tools, service connections, or personalization with dotfiles. For complex initialization with multiple dependent scripts, see Workspace Startup Coordination.

Once these steps have completed, your workspace will now be in the Running state. You can access it via any of the supported methods, stop it when you're away, or delete it once it's no longer in use.

Stopping workspaces

Workspaces may be stopped manually by users and admins in the dashboard, CLI, or API. Workspaces may be automatically stopped due to template updates or inactivity by scheduling configuration.

Once stopped, a workspace may resume running by starting it manually, or via user connection if automatic start is enabled.

Deleting workspaces

Similarly to stopping, workspaces may be deleted manually or automatically by Coder through workspace dormancy.

A delete workspace build runs terraform destroy, destroying both persistent and ephemeral resources. This action can not be reverted.

When enabled on enterprise deployments, workspaces will become dormant after a specified duration of inactivity. Then, if left dormant, the workspaces will be queued for deletion. Learn about configuring workspace dormancy in the template scheduling docs.

Orphan resources

Typically, when a workspace is deleted, all of the workspace's resources are deleted along with it. Rarely, one may wish to delete a workspace without deleting its resources, e.g. a workspace in a broken state. Users with the Template Admin role have the option to do so both in the UI, and also in the CLI by running the delete command with the --orphan flag. This option should be considered cautiously as orphaning may lead to unaccounted cloud resources.

Broken workspace states

During a workspace start or stop build, one of two errors may lead to a broken state. If the call to terraform apply fails to correctly provision resources, a workspace build has failed. If the computational resources fail to connect the agent, a workspace becomes unhealthy.

A failed workspace is most often caused by misalignment from the definition in your template's Terraform file and the target resources on your infrastructure. Unhealthy workspaces are usually caused by a misconfiguration in the agent or workspace startup scripts.

Workspace build times

After a successful build, you can see a timing breakdown of the workspace startup process from the dashboard (starting in v2.17). We capture and display both time taken to provision the workspace's compute and agent startup steps. These include any coder_scripts such as dotfiles or coder_app startups.

Workspace build timings UI

Next steps