Moving to Coder v2

Moving to Coder v2

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.

Coder v2

If you are current a Coder v1 customer and would like to try Coder v2, contact your account executive or contact us.

High-level concepts

Coder v2 introduces a number of new paradigms. We recommend reading the comparison table before you proceed.

Coder v1Coder v2
WorkspaceEach user creates and develops on remote workspacesSame as Coder v1
Supported IDEsWeb IDEs (code-server, Jupyter) + SSH-powered desktop IDEs (e.g. VS Code, JetBrains)Same as Coder v1
ProvisionerProvisions workspaces on Kubernetes with hardcoded spec (pod + home volume)Provisions workspaces via Terraform. Supports any resource (e.g. VM, Kubernetes, Docker)
TemplateOptional YAML configuration syntax for workspaces. Managed by Coder admins or git/CITerraform code that defines workspace specs. Managed by Coder admins or git/CI
ImageContainer image for workspace, contains dev tools and dependenciesContainer and VM image included in the template with dev tools and dependencies
Workspace optionsCPU, RAM, GPU, disk size, image name, CVM (on/off), dotfilesDefined as variables in the template
Deployment methodsKubernetes, DockerKubernetes, Docker, VM, or bare metal
ArchitectureControl plane + PostgreSQL database + workspacesSame as Coder v1

Keep reading for an in-depth feature comparison. Also see the Coder v2 documentation

Migration Strategy

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).

Feature list key

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 v1Coder 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 list


Like 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 v1Coder 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.

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:

  1. Download the Coder v2 CLI
  2. Create a Coder v2 workspace
  3. 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 v1Coder 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 optionsLimited options✅ Any options via template parameters
Edit workspace✅✅
Resource provisoning rates✅ Organization wide✅ Template wide (needs docs)
Manage workspaces through UI and CLI✅✅

Developer experience

Some developer experience features are different, or still being worked on in Coder v2. Refer to this table:

Coder v1Coder 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 v1Coder 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

See the v1 sunset frequently asked questions for more information.

See an opportunity to improve our docs? Make an edit.