Coder v2 is Coder's open core remote development platform first launched in June 2022. Coder v2 has an open-source "OSS" and an Enterprise paid edition. This document shares best practices for moving your workflows from Coder v1 to Coder v2.
If you are current a Coder v1 customer and would like to try Coder v2, contact your account executive or contact us.
Coder v2 introduces a number of new paradigms. We recommend reading the comparison table before you proceed.
| Coder v1 | Coder v2 | |
|---|---|---|
| Workspace | Each user creates and develops on remote workspaces | Same as Coder v1 |
| Supported IDEs | Web IDEs (code-server, Jupyter) + SSH-powered desktop IDEs (e.g. VS Code, JetBrains) | Same as Coder v1 |
| Provisioner | Provisions workspaces on Kubernetes with hardcoded spec (pod + home volume) | Provisions workspaces via Terraform. Supports any resource (e.g. VM, Kubernetes, Docker) |
| Template | Optional YAML configuration syntax for workspaces. Managed by Coder admins or git/CI | Terraform code that defines workspace specs. Managed by Coder admins or git/CI |
| Image | Container image for workspace, contains dev tools and dependencies | Container and VM image included in the template with dev tools and dependencies |
| Workspace options | CPU, RAM, GPU, disk size, image name, CVM (on/off), dotfiles | Defined as variables in the template |
| Deployment methods | Kubernetes, Docker | Kubernetes, Docker, VM, or bare metal |
| Architecture | Control plane + PostgreSQL database + workspaces | Same as Coder v1 |
Keep reading for an in-depth feature comparison. Also see the Coder v2 documentation
A separate control plane is necessary to run Coder v2. A direct upgrade via Helm is not possible since Coder v2 redefines some concepts (e.g. templates, provisioners) and other features are still being developed (e.g. audit log, organization support).
Short term, we recommend keeping your Coder v1 control plane and inviting a pilot group to your Coder v2 control plane to reproduce their workflows and try new features (e.g. Windows support, dynamic secrets, faster builds).
Each of the following features have open issues on coder/coder - if they're a priority for your team, please chime in on the GitHub issue.
✅ = Complete
⌛ = WIP/planned on a roadmap
🤔 = Still considering
❌ = No current plans for feature
For small "proof-of-concept" deployments, you can use Coder's built-in database and tunnel on a VM to avoid setting up a database, reverse proxy, and TLS.
For production use, we recommend running Coder with an external PostgresSQL database and a reverse proxy for TLS.
| Coder v1 | Coder v2 | |
|---|---|---|
| Kubernetes | ✅ Helm chart | ✅ |
| Kubernetes (HA/multiple replicas) | ✅ | ✅ |
| Docker control plane | ✅ | ✅ |
| VM control plane | ❌ | ✅ |
| Built-in PostgreSQL | ✅ | ✅ |
| External PostgreSQL support | ✅ | ✅ |
| External TLS documentation | ✅ | ✅ |
| Multi region/cloud (control plane) | ✅ Multi-region satellites for faster IDE connections. | ✅ |
| Multi region/cloud (workspaces) | ✅ Workspace providers support additional clusters. | ✅ Templates can provision resources in any clouds, clusters, or region |
| Multi region/cloud (tunnel/SSH) | ✅ | ✅ |
Coder v2 uses a separate
command line utility. To use
both CLIs on the same machine, you can install the Coder v2 CLI under a
different name (e.g. coderv2):
curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=coderv2 > /dev/null
# Coder v1 CLI
coder workspaces list
# Coder v2 CLI
coderv2 listLike Coder v1, you can enable SSO via OpenID Connect so that any user in your federation can log in. Coder v2 optionally supports GitHub (Enterprise) and username/password authentication.
If you are interested in a bulk user and/or workspace migration utility, we'd like to hear from you.
| Coder v1 | Coder v2 | |
|---|---|---|
| Dotfiles | ✅ | Per-workspace (dotfiles docs) |
| Generated SSH key | ✅ | ✅ |
| Default shell | ✅ | Per-workspace (with parameters) |
| Auto-start times | ✅ | Per-workspace |
| Git OAuth | ✅ | ✅ |
User-wide settings (e.g. shell, autostart times, dotfiles URL) are not currently supported in Coder v2 (#3506).
To migrate Coder v1 workspaces, you'll need at least one template in your Coder v2 deployment, specifically with the image(s) you support in Coder v1.
- Docs: Adding templates
We recommend manually creating a new workspace in Coder v2 and using a utility
such as scp or rsync to copy the home directory from your v1 workspace.
Inside a v1 workspace, run the following commands to:
- Download the Coder v2 CLI
- Create a Coder v2 workspace
- rsync your files to the new workspace
# Download the Coder v2 CLI (alias "coderv2")
curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=coderv2 > /dev/null
# Log in to the Coder v2 deployment (e.g. coder-v2.example.com)
coderv2 login https://coder-v2.example.com
# Create a workspace
coderv2 create <workspace-name>
# Gain SSH access to v2 workspaces
coderv2 config-ssh -y
# Copy your home directory into the new Coder v2 workspace
rsync \
--recursive \
--itemize-changes \
--info=progress2 \
--links \
--exclude='.cache/' \
$HOME/. coder.$CODER_WORKSPACE_NAME:/home/coder/.Some workspace-level features are different in Coder v2. Refer to this comparison:
| Coder v1 | Coder v2 | |
|---|---|---|
| Kubernetes workspaces | ✅ Hardcoded spec | ✅ Any spec via the template |
| Docker workspaces | ✅ Hardcoded spec | ✅ Any spec via the Terraform template |
| VM workspaces | ❌ | ✅ Any spec via the Terraform template |
| Linux workspaces | ✅ | ✅ |
| Windows workspaces | ✅ | ✅ |
| macOS workspaces | ❌ | ✅ |
| ARM workspaces | ❌ | ✅ |
| Additional resources in workspace (volume mounts, API keys, etc) | ❌ | ✅ Any Terraform resource |
| Workspace options | Limited options | ✅ Any options via template parameters |
| Edit workspace | ✅ | ✅ |
| Resource provisoning rates | ✅ Organization wide | ✅ Template wide (needs docs) |
| Manage workspaces through UI and CLI | ✅ | ✅ |
Some developer experience features are different, or still being worked on in Coder v2. Refer to this table:
| Coder v1 | Coder v2 | |
|---|---|---|
| Auto-start workspace (schedule) | ✅ | ✅ |
| Auto-start workspace (SSH or visit app) | ❌ | See #4973 |
| Code via web terminal | ✅ | ✅ |
| Code via code-server (Code Web) | ✅ Hardcoded version | ✅ Any version via the template |
| Code via JetBrains Projector (web) | ✅ Hardcoded version | ✅ Any version via the template |
| Code with local IDE via SSH (VS Code Remote, JetBrains Gateway) | ✅ With coder-cli installed | ✅ With coder installed |
| Custom workspace applications | ✅ | ✅ Defined in templates |
| Access ports (SSH/tunnel) | ✅ | ✅ |
| Access ports (web UI) | ✅ Dev URLs | ✅ |
| Share ports (web UI) | ✅ Dev URLs | ✅ |
| Docker in workspaces (Kubernetes) | ✅ CVMs | ✅ |
| Manage workspaces through UI and CLI | ✅ | ✅ |
| Open in Coder button | ✅ | ✅ |
Some enterprise features are different, or still being worked on in Coder v2. Refer to this table:
| Coder v1 | Coder v2 | |
|---|---|---|
| Auto-stop workspace | ✅ Activity-based | ✅ Schedule-based & ✅ Activity-based ) |
| Audit logging | ✅ | ✅ |
| Organizations | ✅ | ✅ Groups & template permissions |
| Workspace Proccess Logging | ✅ | ⌛ #5314 |
| User metrics | ✅ | Template-wide metrics (needs docs) |
| Resource quotas | ✅ | ✅ Max workspace limit |
| SDK | ❌ | ✅ codersdk |
| REST API | ✅ | ✅ |
See the v1 sunset frequently asked questions for more information.