Files
coder/docs/install/plan/migrate/dev-box.md
e0b74e6817 docs: add Migrate to Coder section and Microsoft Dev Box migration guide (#31979)
> [!NOTE]
> Coder Agents generated this PR.

Adds a "Migrate to Coder" group to the docs sidebar with a short index
page, and a guide for teams moving from Microsoft Dev Box to Coder.

- `docs/install/plan/migrate.md` (new): says who the guides are for and
lists them.
- `docs/install/plan/migrate/dev-box.md` (new): who it's for, what
carries over, a concept-mapping table, 11 numbered migration steps, and
**Learn more**. The steps cover the inventory, the control plane, Entra
ID (OIDC), templates on Azure (image, network, persistence, access,
quotas), customizations and dotfiles, Git auth and secrets, RDP,
editors, schedules and hibernation, Intune, and the pilot and cut-over.
Each step links to existing Coder docs instead of repeating them.
- `docs/install/plan/migrate/ona.md` (moved from `migrate-from-ona.md`):
relative links only, plus a redirect from
`install/plan/migrate-from-ona` in `docs/redirects.json`.
- `docs/manifest/install/plan/migrate.yml` (new) and
`docs/manifest/install/plan.yml`: the new group, with the Ona guide
under it. This follows the existing `upgrade.md` plus `upgrade/` layout.
`docs/manifest.json` is regenerated.

Microsoft retirement dates come from Microsoft's own [Dev Box retirement
guide](https://learn.microsoft.com/azure/dev-box/dev-box-retirement-guide):
the closing-down period started September 14, 2026, and the service
retires September 18, 2028.

### Follow-ups outside this PR

- **Starter template is broken today.** The registry `azure-windows`
template pins `windows-rdp` at `~> 1.0`, which now resolves to 1.4.0.
That version requires `agent_name`, so `terraform plan` fails with
`agent_name must be set when enable_native_rdp is true.` The copy in
`examples/templates/azure-windows/main.tf` also passes `resource_id =
null`, which 1.4.0 rejects at `terraform init`. The guide tells readers
to set `agent_name = "main"` until both templates are fixed.
- **Activity detection docs.** `docs/workspaces/workspace-scheduling.md`
and `docs/templates/managing-templates/schedule.md` say only some
session types count as activity, but the code counts any connection
through the agent (`agent/agent.go` `Collect`,
`coderd/workspacestats/reporter.go`). The guide follows the code. Those
pages need a separate fix, and an SME should confirm RDP end to end.
- **Comparison page.** The coder.com comparison page compares Coder with
Windows 365 and VDI, not Dev Box, and still says Dev Box is in
"maintenance mode". The guide no longer links to it, so DOCS-1414's
comparison-link item waits until the page is corrected.

<details>
<summary>Reusable outline for future migration guides
(DOCS-1414)</summary>

The repo has no place for page templates, so the outline lives here.

```md
---
title: Migrate from <Platform> to Coder
---

<1 to 2 sentences: who it's for (persona and current setup) and the outcome.>
<Optional: dated facts about the platform, citing the vendor's own announcement.>

## Before you begin
<Access, licenses (mark Premium), cloud permissions.>

## What carries over
<Architecture difference in 2 to 3 sentences. "You can keep" list, then "You rebuild" list.>

## Concept mapping
| <Platform> (link to the vendor's docs for each concept) | Coder (link to Coder docs) |

## Step 1: Inventory your <Platform> resources
## Step 2: Deploy the Coder control plane
## Step 3: Connect your identity provider
## Step 4: Replace <environment definition> with templates
## Step N: Bring your devcontainer.json   (Codespaces, Ona, DevPod)
## Step N: Configure Git authentication and secrets
## Step N: Set up editors (and remote desktops, if relevant)
## Step N: Speed up workspace startup (prebuilt workspaces)
## Step N: Replace schedules and cost controls
## Step N: Move agent workloads
## Step N: Pilot and cut over
<One neutral link to the coder.com comparison page, if one exists and is current.>

## Learn more
```

Rules: facts only, with no scoring or positioning language. Check every
mapping row against the vendor's current public docs and record the date
checked in the PR. Link to Coder docs rather than repeating them. Mark
Premium features inline.

</details>

### Verified against

Microsoft docs checked November 5 and November 10, 2026, in the
MicrosoftDocs/azure-docs source (`articles/dev-box/`) and on
learn.microsoft.com:
- `dev-box-retirement-guide.md` (dates, workload deletion)
- `overview-what-is-microsoft-dev-box.md`,
`concept-dev-box-architecture.md` (dev centers, projects, pools,
definitions, network connections, Microsoft-hosted network, Intune
enrollment, Entra join, Windows 10 and 11 client editions)
- `how-to-manage-dev-box-pools.md` (local admin or standard user
setting)
- `concept-what-are-dev-box-customizations.md`,
`how-to-configure-team-customizations.md`,
`how-to-configure-user-customizations.md` (WinGet, PowerShell, Git-Clone
tasks, Key Vault secrets)
- `how-to-configure-azure-compute-gallery.md`
- `how-to-configure-stop-schedule.md` (one stop time per pool),
`how-to-configure-stop-on-disconnect.md`,
`how-to-configure-dev-box-hibernation.md`,
`how-to-auto-delete-dev-box.md`, `tutorial-dev-box-limits.md` (maximum
dev boxes per developer)
- `concept-dev-box-role-based-access-control.md`,
`how-to-install-dev-box-cli.md`, `how-to-set-up-dev-tunnels.md`,
`quickstart-create-dev-box.md`, `how-to-enable-single-sign-on.md`
- Intune [supported operating
systems](https://learn.microsoft.com/intune/fundamentals/ref-supported-platforms)
(Windows client editions, no Windows Server)

Coder side:
- Registry `azure-windows` template (`main.tf`, `README.md`) and
`examples/templates/azure-windows/`: azurerm resources, Windows Server
2022 image, one resource group, virtual network, and storage account per
workspace, VM deleted on stop, persistent `F:` disk, `windows-rdp`
module, generated admin password shown in metadata, no Entra join, no
`daily_cost`
- Registry `windows-rdp` module at `release/coder/windows-rdp/v1.4.0`:
**Web RDP** (subdomain app) and **RDP Desktop** (Coder Desktop) apps,
`agent_name` validation, Devolutions Gateway install from PowerShell
Gallery on every start. Reproduced the plan failure with Terraform
1.17.1.
- Registry `dotfiles` module: Bash script only
- `cli/dotfiles.go`, `cli/dotfiles_windows.go` (`install.ps1`,
`bootstrap.ps1`, `setup.ps1`, run with PowerShell, cloned with Git)
- `enterprise/coderd/workspacequota.go` (build denied when consumed plus
cost exceeds budget), `docs/admin/users/quotas.md`
- `coderd/schedule/autostop.go` (autostop requirement stops at the start
of quiet hours), `docs/reference/cli/server/index.md`
(`CODER_QUIET_HOURS_DEFAULT_SCHEDULE`, `CODER_ALLOW_CUSTOM_QUIET_HOURS`)
- `docs/workspaces/workspace-access/remote-desktops.md`,
`docs/admin/networking/index.md` (agents must reach the access URL)
- `docs/admin/users/oidc-auth/microsoft.md`,
`docs/admin/users/idp-sync.md`, `docs/admin/users/organizations.md`,
`docs/admin/users/groups-roles.md`,
`docs/templates/template-permissions.md` (Premium markers, organization
roles)
- `coderd/workspacestats/reporter.go`, `coderd/agentapi/stats.go`,
`agent/agent.go` (any connection through the agent extends the autostop
deadline)
- `docs/admin/external-auth.md` (Azure DevOps via Entra ID),
`docs/admin/security/secrets.md`
- `agent/usershell/usershell_windows.go` (scripts run with PowerShell on
Windows)
- No hibernation feature exists in the Coder codebase.

Checks run: `make gen/docs-manifest`, `make pre-commit-light`
(markdownlint, `lint/emdash`, `lint/docs-redirects`, typos), Vale (0
alerts on the new pages), `lint/docs-html`, `lint/docs-manifest`,
`docsredirectscheck -base origin/main -branch main`, a check that all
159 relative links and anchors in the three pages resolve, and a
`doc-check` self-review.

### Open questions for the reviewer
- **Intune and Entra join:** the guide says Coder doesn't enroll
workspaces in Intune, that Intune needs a Windows client image, and
links Microsoft's Entra VM sign-in docs. Should a separate guide cover
setting up Intune with Coder?
- **Windows client editions:** the guide tells readers to check
Microsoft licensing before using Windows 10 or 11 images on Azure VMs.
It makes no licensing claim itself.
- **Windows support in registry modules:** the guide now says the
`dotfiles` module is Bash only. Whether `git-clone` and other modules
work on Windows is unverified.

Closes DOCS-1414, Closes DOCS-1416


Supersedes #31807, reopened under a human author for attribution.

---------

Co-authored-by: Coder Prototypes <294797144+coder-prototypes@users.noreply.github.com>
Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
2026-11-17 22:38:59 +00:00

27 KiB

title
title
Migrate from Microsoft Dev Box to Coder

This guide is for platform engineers who run Microsoft Dev Box and want to move their developer environments to a self-hosted Coder deployment. It maps each Dev Box concept to its Coder equivalent, then walks through the migration, with Windows workspaces on Azure as the main example.

Microsoft's Dev Box retirement guide states that the Dev Box closing-down period began on September 14, 2026, and that the service retires on September 18, 2028. The guide also states that Microsoft expects to delete remaining customer workloads after retirement. Plan to move developer data before the retirement date.

Before you begin

You need:

  • Read access to your dev centers, projects, and pools in the Azure portal, or the Azure CLI with the devcenter extension.
  • An Azure subscription where Coder can create resource groups, virtual machines, disks, virtual networks, network interfaces, and storage accounts. The starter template creates all of these for each workspace.
  • Permission to create an app registration in Microsoft Entra ID.
  • A Coder Premium license if you plan to use the features marked Premium in this guide.

What carries over

Dev Box runs dev boxes in a Microsoft-owned subscription environment and connects them to your network through a network connection. Coder has no vendor-hosted control plane. You run the control plane, and each template provisions workspaces in your own Azure subscription with Terraform.

You can keep:

  • Your Microsoft Entra ID tenant and its users and groups, which Coder uses through OpenID Connect (OIDC).
  • Your Azure virtual networks and subnets, which templates attach workspaces to.
  • Your images in Azure Marketplace or Azure Compute Gallery, which templates reference directly.
  • The scripts behind your customization tasks, which templates or images can run.
  • Your Git hosts, including Azure Repos, GitHub, and GitLab.

You rebuild:

  • Pools, definitions, and image definitions, as Terraform templates.
  • Autostop schedules and cost controls, as template and workspace schedule settings.
  • Remote Desktop access, through Coder instead of the Dev Box developer portal.
  • Device management, such as Microsoft Intune enrollment, if your policies require it. Refer to Step 10: Plan for Intune and device policies.

Concept mapping

Use this table to find where each Dev Box concept lives in Coder. The sections that follow cover each area in detail.

Dev Box Coder
Dev center Your Coder deployment, or an organization (Premium) for each dev center
Project An organization (Premium), or a group (Premium) with template permissions (Premium)
Dev box pool A template, with parameters or workspace presets
Dev box definition or image definition The image, VM size, and disks in a template
Marketplace image or Azure Compute Gallery image The same image, referenced in the template's virtual machine resource
Team customizations Startup scripts and modules in the template, or a prebuilt image
User customizations Dotfiles
Network connection The virtual network and subnet that the template attaches workspaces to
Dev box Workspace
Developer portal Coder dashboard
Azure CLI devcenter extension Coder CLI
DevCenter Project Admin and Dev Box User roles Organization roles, such as Organization Template Admin, for Project Admin, and template permissions (Premium) for Dev Box User
Dev box limits Quotas (Premium)
Autostop schedule Autostop requirement and quiet hours (Premium)
Stop on disconnect Activity detection
Hibernation No equivalent; a workspace stop keeps only the resources the template persists
Auto-delete (preview) Dormancy threshold and dormancy auto-deletion (Premium)
Remote Desktop through Windows App or a browser (connect to a dev box) Remote desktops over Remote Desktop Protocol (RDP), from a desktop client or a browser
Dev tunnels for VS Code VS Code and other editors over SSH
Microsoft Entra ID sign-in to the developer portal OIDC with Microsoft Entra ID
Intune enrollment No built-in equivalent; refer to Step 10: Plan for Intune and device policies

Step 1: Inventory your Dev Box resources

Record the current configuration before you change anything. You use this inventory to build templates and to confirm that nothing was left behind.

Collect the following from the Azure portal or the Azure CLI:

  • Dev centers and projects: which teams each project serves, and who holds each role on it.
  • Pools: the image, compute size, storage size, network connection, region, local administrator setting, and autostop schedule of each pool.
  • Images: each image definition, dev box definition, Marketplace image, and Azure Compute Gallery image that pools use.
  • Customizations: the catalogs attached to each dev center and project, and the tasks in each image definition file.
  • Network connections: the virtual network, subnet, and join type (Microsoft Entra join or Microsoft Entra hybrid join) of each one.
  • Secrets: each Azure Key Vault secret that customization files reference.
  • Cost controls: hibernation, stop on disconnect, auto-delete, and dev box limits for each project and pool.

Step 2: Deploy the Coder control plane

Deploy Coder in Azure, close to the virtual networks that your network connections use.

  1. Size the deployment with the Coder validated architectures.
  2. Install the control plane on Kubernetes, such as Azure Kubernetes Service (AKS), or on an Azure VM.
  3. Connect an external PostgreSQL database, such as Azure Database for PostgreSQL.
  4. Set the access URL and wildcard access URL.
  5. Give the provisioners Azure credentials, as described in Provider authentication.

If your pools span several regions, deploy workspace proxies (Premium) near each group of developers.

Step 3: Connect Microsoft Entra ID

Connect the same Entra ID tenant that Dev Box uses, so developers sign in with their existing accounts.

  1. Configure OIDC with Microsoft Entra ID.
  2. To map Entra ID groups to Coder groups, configure group sync (Premium).
  3. If you map each project to its own organization, configure organization sync (Premium).

Coder OIDC controls sign-in to Coder. It doesn't sign developers in to Windows inside the workspace. Refer to Step 7: Connect over Remote Desktop for Windows sign-in.

Step 4: Replace pools with templates

A Dev Box pool combines an image, a compute size, storage, a network connection, and schedule settings. In Coder, a template's Terraform defines the first 4, and the template's schedule settings define the rest.

Start from the Azure VM (Windows) template

The Azure VM (Windows) template in the Coder Registry is a starting point for Windows workspaces. It uses the azurerm Terraform provider to create a Windows Server virtual machine, a network interface, and a data disk in a resource group for each workspace. For Linux workspaces, start from the Azure VM (Linux) template instead.

If the template's windows_rdp module block doesn't set agent_name, add agent_name = "main", the name of the template's coder_agent resource. Without it, the template fails to build and reports that agent_name must be set when enable_native_rdp is true.

Create one template for each group of pools that share an image and network. To offer several compute sizes in one template, add a parameter for the VM size. To give each team a preconfigured starting point, add a workspace preset for each pool.

Choose the image

Set the image in the template's azurerm_windows_virtual_machine resource:

  • For a Marketplace image, set the publisher, offer, sku, and version values in source_image_reference.
  • For an Azure Compute Gallery image, set source_image_id to the gallery image ID.

The starter template uses a Windows Server image, and Dev Box supports Windows 10 and Windows 11 client editions. If you switch the template to a client edition, confirm with Microsoft licensing guidance that you can run it on Azure virtual machines.

Attach workspaces to your network

The starter template creates a virtual network for each workspace. To keep the network access that a Dev Box network connection provides, change the template to use your existing subnet. For example, read the subnet with an azurerm_subnet data source and pass its ID to the network interface. The Azure credentials that the provisioners use also need permission to join that subnet.

Workspaces on the subnet need outbound access to your Coder access URL, which the Coder agent uses to connect. The Windows RDP module also downloads Devolutions Gateway from the internet each time the workspace starts. Refer to Networking for the connections that the agent makes.

Pools that use a Microsoft-hosted network have no subnet to reuse, so keep the starter template's virtual network for those pools.

Keep data across restarts

By default, the starter template deletes the virtual machine when the workspace stops and keeps the data disk mounted as F:. Files outside the data disk don't persist. The template README describes how to keep the whole virtual machine and deallocate it on stop instead. That approach needs the Azure CLI (az) on the provisioner's PATH, and the official Coder images don't include it. Refer to Resource persistence to choose what to keep.

Control who uses each template

Dev Box grants access with the Dev Box User role on a project. In Coder, use template permissions (Premium) to limit each template to the groups that need it. To limit how many workspaces each developer runs, as Dev Box limits do, configure quotas (Premium). Quotas give each developer a credit budget from the allowances of their groups. Coder calculates each developer's budget separately in each organization. A workspace spends credits only for resources that have a daily_cost, and the starter template sets none, so quotas don't limit its workspaces until you add one.

To allow each developer a set number of workspaces, give the data disk a cost of 1 credit, and give each developer's groups allowances that add up to the limit:

resource "coder_metadata" "data_disk" {
  resource_id = azurerm_managed_disk.data.id
  daily_cost  = 1
}

The data disk persists while the workspace is stopped, so stopped workspaces also count toward the limit.

Step 5: Translate customizations

Dev Box team customizations run WinGet, PowerShell, and Git clone tasks from an image definition file. Coder has no equivalent file, so move each task to the image or to the template:

  • Tasks that rarely change: bake them into a custom image in your Azure Compute Gallery. This keeps workspace startup fast.
  • Tasks that run on every start: add a coder_script to the template. On Windows, the Coder agent runs scripts with PowerShell.
  • Developer-specific tasks: ask developers to move their user customizations to a dotfiles repository. The Dotfiles module runs a Bash script, so it doesn't run on Windows workspaces. On Windows, coder dotfiles runs the first of install.ps1, bootstrap.ps1, or setup.ps1 that it finds in the repository root or its script folder, with PowerShell. It clones the repository with Git, so install Git in the image.

Refer to Speed up your workspaces for more ways to reduce startup time.

Step 6: Configure Git authentication and secrets

Dev Box customization files can read secrets from Azure Key Vault to clone private repositories. In Coder, developers authorize their own Git accounts through external authentication:

  1. Create an OAuth application on each Git host, or an Entra ID app registration for Azure DevOps.
  2. Add each provider to Coder with the CODER_EXTERNAL_AUTH_<n>_* environment variables.
  3. For Azure Repos, use the Azure DevOps (via Entra ID) provider type.
  4. Add the external authentication provider to each template.

Move other secrets as follows:

  • Shared secrets: give the workspace VM a managed identity and read values from Azure Key Vault at startup. Do not put secret values in template code or parameters. Coder shows parameter values in cleartext to anyone who can view the workspace.
  • Personal secrets: ask developers to recreate them as user secrets.

Refer to Secrets for more options.

Step 7: Connect over Remote Desktop

Dev Box connects developers through Windows App or a browser. Coder connects to Windows workspaces over RDP through the Coder agent, so workspaces need no public IP address.

The starter template includes the Windows RDP module, which adds these buttons to the workspace page:

  • Web RDP: opens an RDP session in the browser. It needs the wildcard access URL from Step 2.
  • RDP Desktop: opens the session in a desktop RDP client through Coder Desktop.

Developers without Coder Desktop can forward the RDP port with coder port-forward and connect with any RDP client. Refer to Remote desktops for each method.

The starter template creates a local administrator account with a generated password, and shows both on the workspace page while the workspace runs. It doesn't join the VM to Entra ID, so developers don't sign in to Windows with their Entra ID account. If your Dev Box pools gave developers standard user accounts, change the template to match.

Step 8: Set up editors

Developers who used Dev Box dev tunnels with VS Code can connect to Coder workspaces over SSH instead:

Developers who run Visual Studio or other desktop tools inside Windows keep using them over RDP.

Step 9: Replace schedules and hibernation

Recreate each cost control in your inventory with the matching Coder setting:

  • Autostop schedule: Dev Box stops every dev box in a pool at one time of day. To stop workspaces at a set time in Coder, configure a daily autostop requirement (Premium) on the template. Workspaces then stop at the start of each developer's quiet hours (Premium), even if they're in use. Set the default quiet hours with CODER_QUIET_HOURS_DEFAULT_SCHEDULE, and set CODER_ALLOW_CUSTOM_QUIET_HOURS=false so that developers can't change them. Unlike a Dev Box schedule, the default quiet hours apply to the whole deployment, not to one template. To stop idle workspaces instead, set a default autostop on the template, and let developers set autostart and autostop.
  • Stop on disconnect: Coder extends the autostop deadline by the template's activity bump duration when it detects activity. It stops the workspace after the deadline passes with no activity. Traffic through the Coder agent counts as activity, including RDP sessions that connect through Coder. Refer to activity detection.
  • Hibernation: Coder has no equivalent. Open applications don't survive a workspace stop, and the template decides which disks persist.
  • Auto-delete: configure the dormancy threshold and dormancy auto-deletion (Premium).
  • Required restarts: to apply image and template updates on a schedule, configure an autostop requirement (Premium).

Step 10: Plan for Intune and device policies

Dev Box enrolls each dev box in Microsoft Intune and joins it to Entra ID or Active Directory through the network connection. Coder doesn't enroll workspaces in Intune or join them to a directory.

If your security policies require managed devices, configure the device join and Intune enrollment in the image or the template. Intune's list of supported operating systems includes Windows client editions, such as Windows 11 Enterprise, but not Windows Server, which the starter template uses. To enroll workspaces, first switch the template to a client edition image, as described in Choose the image. For Entra ID join and Entra ID sign-in on Azure virtual machines, follow Microsoft's guide to sign in to a Windows VM with Microsoft Entra ID. If you use conditional access policies that require a compliant device, test them from a pilot workspace before you move developers.

Step 11: Pilot and cut over

  1. Run Coder and Dev Box side by side.
  2. Move one team and one pool to Coder first.
  3. Compare workspace startup time and developer feedback with the same pool on Dev Box.
  4. Ask developers to commit their work to Git.
  5. Ask developers to copy the local files they need from each dev box.
  6. Move the remaining pools one at a time.
  7. After all developers move, delete your Dev Box resources by following the Dev Box retirement guide.

Learn more