Files
coder/docs/workspaces/workspace-management.md
T
Jaayden HalkoandJake Howell d1a58b9f5d feat: add script to check for title case (#21484)
Historically, much of the UI used title case. This PR adds a lint check
that reports title case UI text so it can be converted to sentence case,
and converts the existing text.

- `site/scripts/check-sentence-case.mjs` runs as `pnpm
lint:sentence-case` and is part of `pnpm lint`. It reads JSX text and
string/template literals from the TypeScript AST and skips literals that
are code rather than UI text (imports, types, property names, tagged
templates, values of JSX attributes that are not displayed such as
`className` or `style`, and operands of `===`/`case` comparisons). JSX
text across inline elements and conditional JSX is checked as one
phrase. `--fix` lowercases the reported words. The checker is a
heuristic: it is not meant to model every code shape, so use a
`sentence-case-expect` comment where it guesses wrong.
- Proper nouns (Coder products, role names, third-party products,
protocols, font names) live in `PROPER_NOUNS`. For other deliberate
exceptions, a `sentence-case-expect` comment on the line above
suppresses the report and fails when that line no longer needs it.
- Existing UI text is converted to sentence case, and tests that assert
on it are updated.
- Deployment option lookups (`useDeploymentOptions`) now use CLI flags
instead of display names, so they do not depend on UI wording.

## Performance

`pnpm lint:sentence-case` takes **1.6 s** and is 2% to 4.5% of `pnpm
lint`. Measured on 82317c925e in a dev workspace (Xeon Platinum 8375C,
16 vCPUs, Node 22.23.4, TypeScript 6.0.2, warm file cache). CI buffers
the output of the lint steps, so its log has no per-step times to
compare against.

| Measurement (20 runs) | Result |
|---|---|
| Wall time | 1.64 s mean, 0.03 s standard deviation, 1.62 s to 1.71 s |
| CPU time | 3.0 s |
| Peak memory (RSS) | 154 MB, of which 116 MB is Node with `typescript`
loaded |
| Input | 1,301 of the 2,199 `.ts` and `.tsx` files in `site/src` (the
rest are excluded), 210,684 lines, 6.1 MB |
| Throughput | About 130,000 lines per second |
| Time per file | 0.5 ms median, 3 ms at the 95th percentile, 76 ms
maximum (`src/api/api.ts`, 121 KB) |

Each step of `pnpm lint`, median wall time of 5 runs:

| Step | Wall time |
|---|---|
| `lint:check` (Biome) | 0.96 s |
| `lint:oxlint` | 0.32 s |
| `lint:types` (`tsc`) | 5.8 s with its incremental cache, 45 s without
|
| `lint:circular-deps` | 5.7 s |
| `lint:compiler` | 15.6 s |
| `lint:sentence-case` | 1.6 s |
| `knip` | 6.6 s |
| All of `pnpm lint` | 37 s with the `tsc` cache, 76 s without |

<details>
<summary>Where the time goes, scaling, and limits</summary>

Phases of one run, from in-process timers. The split between parsing and
checking is approximate.

| Phase | Time | Share |
|---|---|---|
| Node startup | 0.03 s | 2% |
| Load the `typescript` module | 0.32 s | 20% |
| Find and read the files | 0.04 s | 2% |
| Parse (`ts.createSourceFile`) | 0.83 s | 52% |
| Check logic | 0.38 s | 24% |

Scaling, from synthetic inputs passed to `checkSource` (median of 3 to 5
warm runs):

- Clean input is linear in size: 0.2 ms to 0.35 ms per KB for one file
from 54 KB to 7 MB. 100,000 string literals take 0.3 s, 100,000 sibling
JSX elements take 0.8 s, and JSX nested 800 levels deep takes 10 ms.
- Conditional JSX stays bounded by the 64-variant cap: 1 to 48
conditional children in one element take at most 3.4 ms.
- Reporting and fixing add no measurable time. On the merge base with
`main` (378 reports in 175 files), a check, `--fix`, and a second
`--fix` each take 1.6 s to 1.7 s.
- The 21 unit tests run in about 30 ms, 1.7 s including Vitest startup.

Two limits, neither reachable with the current source:

- Time is quadratic in the reports for one file, because the fixed text
is rebuilt once per report. A 3.5 MB file takes 0.7 s clean and 18.0 s
with 12,800 reports. The most reports in one file on the merge base is
16.
- One JSX element with more than about 120,000 text phrases fails with
`RangeError: Maximum call stack size exceeded`, because the phrases are
spread into `push`.

</details>

---------

Co-authored-by: Jake Howell <jake@hwll.me>
2026-11-18 13:36:16 +07:00

9.4 KiB

title
title
Manage workspaces

A workspace is the environment where a developer or a coding agent works. Developers and agents in a team each work from their own workspace and can use multiple IDEs.

A developer creates a workspace from a shared template. This lets an entire team work in environments that are identically configured and provisioned with the same resources.

Create workspaces

You can create a workspace in the UI. Log in to your Coder instance, go to the Templates tab, find the template you need, and select Create workspace.

Creating a workspace in the UI

When you create a workspace, you will be prompted to give it a name. You might also be prompted to set some parameters that the template provides.

You can manage your existing templates in the Workspaces tab.

You can also create a workspace from the command line:

Each Coder user has their own workspaces created from templates:

# create a workspace from the template; specify any variables
coder create --template="<templateName>" <workspaceName>

# show the resources behind the workspace and how to connect
coder show <workspace-name>

Workspace name rules and restrictions

Constraint Rule
Start/end with Must start and end with a letter or number
Character types Letters, numbers, and hyphens only
Length 1-32 characters
Case sensitivity Case-insensitive (lowercase recommended)
Reserved names Cannot use new or create
Uniqueness Must be unique within your workspaces

Renaming a workspace after you create it is off by default. A template admin can allow it per template. Refer to Workspace renaming.

Workspace filtering

In the Coder UI, you can filter your workspaces using pre-defined filters or Coder's filter query. Filters follow the pattern [filter name]:[filter text] and multiple filters can be specified separated by a space, that is, owner:me status:running

The following filters are supported:

  • owner - Represents the username of the owner. You can also use me as a convenient alias for the logged-in user, for example, owner:me
  • user - Workspaces a user owns, plus workspaces shared with them directly or through a group they belong to. Accepts a username, user ID, or me, for example, user:me
  • name - Name of the workspace.
  • template - Name of the template.
  • status - Indicates the status of the workspace, for example, status:failed For a list of supported statuses, see WorkspaceStatus documentation.
  • outdated - Filters workspaces using an outdated template version, for example, outdated:true
  • dormant - Filters workspaces based on the dormant state, for example, dormant:true
  • has-agent - Only applicable for workspaces in "start" transition. Stopped and deleted workspaces don't have agents. List of supported values connecting|connected|timeout|disconnected, for example, has-agent:connecting
  • id - Workspace universally unique identifier (UUID)
  • healthy - Only applicable for workspaces in "start" transition. healthy:false is an alias for has-agent:timeout,disconnected, healthy:true is an alias for has-agent:connected.
  • include_agent_metadata - Not a filter: expands each agent in the API response with the named agent metadata keys, for example, include_agent_metadata:cpu_usage. Repeat the key to request multiple metadata items. Keys match case-insensitively.

Update workspaces

After updating the default version of the template that a workspace was created from, you can update the workspace.

Updating a workspace

If the workspace is running, Coder stops it, updates it, then starts the workspace again.

Update with the CLI

Update a workspace through the command line:

coder update <workspace-name>

If the workspace is running, coder update asks for confirmation before it stops and updates the workspace. To skip the prompt in scripts and other non-interactive use, add -y:

coder update -y <workspace-name>

By default, coder update stops the workspace with its current template version and starts it on the active version. To start on a specific version instead, use --template-version with the version name or ID. To stop with a different version than the workspace's current one, use --stop-template-version:

coder update <workspace-name> --template-version <version-name>
coder update <workspace-name> --stop-template-version <version-name> --template-version <version-name>

--stop-template-version only applies when coder update stops a started workspace. To stop a workspace with a specific version on its own, use coder stop --template-version.

coder start and coder stop also accept --template-version. Template permissions still apply, so if a template requires the active version, only template admins can start a workspace on another version.

Automatic updates

It can be tedious to manually update a workspace everytime an update is pushed to a template. Users can choose to opt-in to automatic updates to update to the active template version whenever the workspace is started.

Note: If a template is updated such that new parameter inputs are required from the user, autostart will be disabled for the workspace until the user has manually updated the workspace.

Automatic updates

Bulk operations

Admins can apply bulk operations (update, delete, start, stop) in the Workspaces tab. Select the workspaces you'd like to modify with the checkboxes on the left, then use the top-right Actions dropdown to apply the operation.

The start and stop operations can be applied even when the selected workspaces are not all in the same state. Bulk start will only apply to selected workspaces that are currently stopped, and bulk stop will only apply to selected workspaces that are currently running. For update, delete, and stop, the admin applying the operation is prompted for confirmation before any action is taken. The owners of the selected workspaces are not prompted.

Bulk workspace actions

Start and stop workspaces

By default, you manually start and stop workspaces as you need. You can also schedule a workspace to start and stop automatically.

To set a workspace's schedule, go to the workspace, then Settings > Schedule.

Scheduling UI

Coder might also stop a workspace automatically if there is a template update available.

Learn more about workspace lifecycle and our scheduling features.

Workspace resources

Workspaces in Coder are started and stopped, often based on whether there was any activity or if there was a template update available.

Resources are often destroyed and re-created when a workspace is restarted, though the exact behavior depends on the template. For more information, see Resource Persistence.

Repair workspaces

Use the following command to re-enter template input variables in an existing workspace. This command is useful when a workspace fails to build because its state is out of sync with the template.

coder update <your workspace name> --always-prompt

First, try re-entering parameters from a workspace. In the Coder UI, you can filter your workspaces using pre-defined filters or employing the Coder's filter query. Take a look at the following examples to understand how to use the Coder's filter query:

  • To find the workspaces that you own, use the filter owner:me.
  • To find workspaces that are currently running, use the filter status:running.

Re-entering template variables

You can also do this in the CLI with the following command:

coder update <your workspace name> --always-prompt

If that does not work, a Coder admin can manually push and pull the Terraform state for a given workspace. This can lead to state corruption or deleted resources if you do not know what you are doing.

coder state pull <username>/<workspace name>
# Make changes
coder state push <username>/<workspace name>

Logging

Coder stores macOS and Linux logs at the following locations:

Service Location
startup_script /tmp/coder-startup-script.log
shutdown_script /tmp/coder-shutdown-script.log
Agent /tmp/coder-agent.log

Note

The agent log rotates when it reaches 5 MB in size, and Coder keeps up to 19 rotated files. The startup and shutdown script log files in the workspace have no size limit.