## 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).
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 synccommand 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:
- Create a test workspace from the updated template
- Check workspace build logs for sync messages
- Verify all units reach "completed" status using
coder exp sync list - 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:
sleepcommands 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.