Files
coder/docs/admin/templates/startup-coordination/usage.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

6.8 KiB

title
title
Workspace startup coordination usage

Note

This feature is experimental and may change without notice in future releases.

Startup coordination is built around the concept of units. You declare units in your Coder workspace template using the coder exp sync command in coder_script resources. When the Coder agent starts, it keeps an in-memory directed acyclic graph (DAG) of all units of which it is aware. When you need to synchronize with another unit, you can use coder exp sync start $UNIT_NAME to block until all dependencies of that unit have been marked complete.

What is a unit?

A unit is a named phase of work, typically corresponding to a script or initialization task.

  • Units may declare dependencies on other units, creating an explicit ordering for workspace initialization.
  • Units must be registered before they can be marked as complete.
  • Units may be marked as dependencies before they are registered.
  • Units must not declare cyclic dependencies. Attempting to create a cyclic dependency will result in an error.

Requirements

Important

The coder exp sync command is only available from Coder version >=v2.30 onwards.

To use startup dependencies in your templates, you must:

  • Modify your workspace startup scripts to run in parallel
  • Declare dependencies as required using coder exp sync

Declare Dependencies in your Workspace Startup Scripts

Single Dependency

Here's a simple example of a script that depends on another unit completing first:

#!/bin/bash
UNIT_NAME="my-setup"

# Declare dependency on git-clone
coder exp sync want "$UNIT_NAME" "git-clone"

# Wait for dependencies and mark as started
coder exp sync start "$UNIT_NAME"

# Do your work here
echo "Running after git-clone completes"

# Signal completion
coder exp sync complete "$UNIT_NAME"

This script will wait until the git-clone unit completes before starting its own work.

Multiple Dependencies

If your unit depends on multiple other units, you can declare all dependencies before starting:

#!/bin/bash
UNIT_NAME="my-app"
DEPENDENCIES="git-clone,env-setup,database-migration"

# Declare all dependencies
if [ -n "$DEPENDENCIES" ]; then
  IFS=',' read -ra DEPS <<< "$DEPENDENCIES"
  for dep in "${DEPS[@]}"; do
    dep=$(echo "$dep" | xargs)  # Trim whitespace
    if [ -n "$dep" ]; then
      coder exp sync want "$UNIT_NAME" "$dep"
    fi
  done
fi

# Wait for all dependencies
coder exp sync start "$UNIT_NAME"

# Your work here
echo "All dependencies satisfied, starting application"

# Signal completion
coder exp sync complete "$UNIT_NAME"

Inspect Unit State

Use coder exp sync list to see all registered units and their current state:

coder exp sync list

Example output:

UNIT           STATUS     READY
git-clone      completed  true
env-setup      started    true
ide-configure  pending    false

To inspect a single unit and its dependencies in detail, use coder exp sync status <unit>.

To verify the agent socket is reachable, use coder exp sync ping.

Best Practices

Test your changes before rolling out to all users

Before rolling out to all users:

  1. Create a test workspace from the updated template
  2. Check workspace build logs for sync messages
  3. Verify all units reach "completed" status using coder exp sync list
  4. Test workspace functionality

Once you're satisfied, promote the new template version.

Handle missing CLI gracefully

Not all workspaces will have the Coder CLI available in $PATH. Check for availability of the Coder CLI before using sync commands:

if command -v coder > /dev/null 2>&1; then
  coder exp sync start "$UNIT_NAME"
else
  echo "Coder CLI not available, continuing without coordination"
fi

Complete units that start successfully

Units must call coder exp sync complete to unblock dependent units. Use trap to ensure completion even if your script exits early or encounters errors:


SYNC_STARTED=0
if coder exp sync start "$UNIT_NAME"; then
  SYNC_STARTED=1
fi

cleanup_sync() {
  if [ "$SYNC_STARTED" -eq 1 ]; then
    coder exp sync complete "$UNIT_NAME"
  fi
}
trap cleanup_sync EXIT

Use descriptive unit names

Names should explain what the unit does, not its position in a sequence:

  • Good: git-clone, env-setup, database-migration
  • Avoid: step1, init, script-1

Prefix a unique name to your units

When using coder exp sync in modules, note that unit names like git-clone might be common. Prefix the name of your module to your units to ensure that your unit does not conflict with others.

  • Good: <module>.git-clone, <module>.claude
  • Bad: git-clone, claude

Document dependencies

Add comments explaining why dependencies exist:

resource "coder_script" "ide_setup" {
  # Depends on git-clone because we need .vscode/extensions.json
  # Depends on env-setup because we need $NODE_PATH configured
  script = <<-EOT
    coder exp sync want "ide-setup" "git-clone"
    coder exp sync want "ide-setup" "env-setup"
    # ...
  EOT
}

Avoid circular dependencies

The Coder Agent detects and rejects circular dependencies, but they indicate a design problem:

# This will fail
coder exp sync want "unit-a" "unit-b"
coder exp sync want "unit-b" "unit-a"

Frequently Asked Questions

How do I identify scripts that can benefit from startup coordination?

Look for these patterns in existing templates:

  • sleep commands used to order scripts
  • Using files to coordinate startup between scripts (e.g. touch /tmp/startup-complete)
  • Scripts that fail intermittently on startup
  • Comments like "must run after X" or "wait for Y"

Will this slow down my workspace?

No. The socket server adds minimal overhead, and the default polling interval is 1 second, so waiting for dependencies adds at most a few seconds to startup. You are more likely to notice an improvement in startup times as it becomes easier to manage complex dependencies in parallel.

How do units interact with each other?

Units with no dependencies run immediately and in parallel. Only units with unsatisfied dependencies wait for their dependencies.

How long can a dependency take to complete?

By default, coder exp sync start has a 5-minute timeout to prevent indefinite hangs. Upon timeout, the command will exit with an error code and print timeout waiting for dependencies of unit <unit_name> to stderr.

You can adjust this timeout as necessary for long-running operations:

coder exp sync start "long-operation" --timeout 10m

Is state stored between restarts?

No. Sync state is kept in-memory only and resets on workspace restart. This is intentional to ensure clean initialization on every start.