Coder has open-sourced a new remote development platform 🥳 Check it out at coder/coder on GitHub.

Moving to Coder OSS

Coder OSS is Coder's open core remote development platform first launched in June 2022. This document shares best practices for moving your workflows from Coder v1 to Coder OSS.

Coder OSS
Dashboard

If you are current a Coder v1 customer and would like to try Coder OSS, we'd like to hear from you to help inform our roadmap and migration strategy.

High-level concepts

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

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

Migration Strategy

A separate control plane is necessary to run Coder OSS. A direct upgrade via Helm is not possible since Coder OSS 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 OSS 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

Infrastructure

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 OSS
Kubernetes✅ Helm chart⌛ Helm chart (needs docs)
Kubernetes (HA/multiple replicas)✅⌛ #3502
Docker control plane✅✅
VM control plane❌✅
Built-in PostgreSQL✅✅
External PostgreSQL support✅✅
External TLS documentation✅⌛ #3518
Multi region/cloud (control plane)✅ Multi-region satellites for faster IDE connections.⌛ #3227
Multi region/cloud (workspaces)✅ Workspace providers support additional clusters.✅ Templates can provision resources in any clouds, clusters, or region
Multi region/cloud (tunnel/SSH)✅✅

Something missing, or have feedback? Let us know

CLI

Coder OSS uses a separate command line utility. To use both CLIs on the same machine, you can install the Coder OSS CLI under a different name (e.g. codeross):

curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=codeross > /dev/null

# Coder v1 CLI
coder workspaces list

# Coder OSS CLI
codeross list

Users

Like Coder v1, you can enable SSO via OpenID Connect so that any user in your federation can log in. Coder OSS 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 OSS
Dotfiles✅Per-workspace (dotfiles docs)
Generated SSH key✅✅
Default shell✅Per-workspace (with parameters)
Auto-start times✅Per-workspace
Git OAuth✅SSH key only (#3078)

Something missing, or have feedback? Let us know

User-wide settings (e.g. shell, autostart times, dotfiles URL) are not currently supported in Coder OSS (#3506).

Workspaces

If you are interested in a bulk user and/or workspace migration utility, we'd like to hear from you.

To migrate Coder v1 workspaces, you'll need at least one template in your Coder OSS deployment, specifically with the image(s) you support in Coder v1.

We recommend manually creating a new workspace in Coder OSS 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 OSS CLI
  2. Create a Coder OSS workspace
  3. rsync your files to the new workspace
# Download the Coder OSS CLI (alias "codeross")
curl -sL https://coder.com/install.sh | sh -s -- --method=standalone --binary-name=codeross > /dev/null

# Log in to the Coder OSS deployment (e.g. coder-v2.example.com)
codeross login https://coder-v2.example.com

# Create a workspace
codeross create <workspace-name>

# Gain SSH access to v2 workspaces
codeross config-ssh -y

# Copy your home directory into the new Coder OSS 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 OSS. Refer to this comparison:

Coder v1Coder OSS
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✅⌛ #802
Resource provisoning rates✅ Organization wide✅ Template wide (needs docs)
Manage workspaces through UI and CLI✅✅

Something missing, or have feedback? Let us know

Developer experience

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

Coder v1Coder OSS
Auto-start workspace (schedule)✅✅
Auto-start workspace (SSH or visit app)❌🤔 #2909
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⌛ (#1624)
Share ports (web UI)✅ Dev URLs⌛ (#3515)
Docker in workspaces (Kubernetes)✅ CVMs✅
Manage workspaces through UI and CLI✅✅
Open in Coder button✅🤔 (needs docs)

Something missing, or have feedback? Let us know

Enterprise/management

Some enterprise features are different, or still being worked on in Coder OSS. Refer to this table:

Coder v1Coder OSS
Auto-stop workspace✅ Activity-based✅ Schedule-based & ⌛ Activity-based (#2995)
Audit logging✅✅
Organizations✅❌ #3039
User metrics✅Template-wide metrics (needs docs)
Resource quotas✅⌛ #2988
SDK❌✅ codersdk
REST API✅🤔 (needs docs)

Something missing, or have feedback? Let us know

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