> [!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>