Coder powers secure, scalable development across key industries — automotive, finance, government, and technology — enabling faster builds, tighter compliance, and seamless AI adoption in enterprise-grade cloud environments.
A workspace is the environment that a developer works in. Developers 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.
Creating 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.
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
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 i.e
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, e.g., owner:me
name - Name of the workspace.
template - Name of the template.
status - Indicates the status of the workspace, e.g, status:failed For a
list of supported statuses, see
WorkspaceStatus documentation.
outdated - Filters workspaces using an outdated template version, e.g,
outdated:true
dormant - Filters workspaces based on the dormant state, e.g 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, e.g, has-agent:connecting
id - Workspace 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.
Updating workspaces
After updating the default version of the template that a workspace was created
from, you can update the workspace.
If the workspace is running, Coder stops it, updates it, then starts the
workspace again.
Updating via the CLI
Update a workspace through the command line:
coder update <workspace-name>
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.
Bulk operations
Admins may 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 and delete, the user will be prompted for
confirmation before any action is taken.
Starting and stopping 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.
Coder might also stop a workspace automatically if there is a
template update
available.
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.
Repairing 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.
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.
You can also do this in the CLI with the following command:
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:
