ACP promises to connect a third-party agent, and the first word you run into is registry. The name misleads: it sounds like a catalog you pick and install agents from, like extensions from a store or packages from npm. In fact the local ACP registry works differently, and misreading it is the first and most frequent source of the complaint "the agent is added but will not start". The mistake is not in the hands or in the config as such, but in the model of what this file even does.
The naive move is clear: since it is a registry, the agents themselves must live in it; add an entry and the environment downloads the binary, allows it and launches it. Hence the expectation that it is enough to write a name and a version, and Desktop takes on delivery, updates and launch. The store model is so familiar from other tools that it is carried over automatically, without checking whether it applies here at all.
It breaks on the very first launch. Devin Desktop does not download the binary from the registry: the executable must already be on the machine, and the registry entry only describes what launches it and how. The file holds a distribution.binary.<platform> section: the launch command and arguments per operating system. The difference is fundamental: a store is responsible for delivery and version, a launch map only for how to call what is already delivered. So the entry has neither a download link nor a checksum - only the path to the executable and the list of arguments with which Desktop brings up a local subprocess on your platform.
The file itself lives at the old path, and that is a separate trap. Stable reads ~/.windsurf/acp/registry.json, Next reads ~/.windsurf-next/acp/registry.json. The .windsurf directory name is kept after the rebrand: it is not a typo or a forgotten artifact but a Windsurf legacy worth knowing in advance, or a search for the word Devin finds nothing. You do not need to hunt the disk for the file at all - the Open Local ACP Registry Config command in the palette opens exactly the file the current build line reads, and thereby settles whether you are on stable or Next.
One entry in the registry is not enough, and this is the second decision that is easy to skip. The agent still has to be enabled: the palette, Devin User Settings, the Agents tab, the toggle for the agent you need - and a restart of Desktop. The registry says what to launch; the Agents setting says that this agent is allowed to run at all. Two different levels: one describes the mechanics, the other gives consent. Skipping the second is the most frequent reason a syntactically correct entry produces no visible effect whatsoever, and why the bug hunt goes the wrong way.
Authentication is kept separate - and this is not a formatting detail but a security boundary. Usually you log the agent in with its own /login command inside the session, or set environment variables - through the "..." button on the Agents tab or the devin.acp.agentEnv.<agentName> key in settings.json. The registry describes the launch, not the secrets, and that split makes sense: a launch config and a credential store live by different rules and change at a different pace.
The documentation does not directly require or forbid keeping a token in registry.json itself, but as engineering it is a poor place, and the conclusion here matters more than the letter. The file describes a launch, often ends up in dotfiles and in sync between machines, and a secret in it leaks along with the config, quietly and for a long time. So credentials are kept in the environment or in /login, where they have their own lifecycle policy and their own scope, while the registry stays a clean launch declaration. This is a conclusion from the design, not a product clause, but the cost of a mistake here is measured not in a log line but in a leaked token.
A local registry is justified when a third-party agent is genuinely needed in your ecosystem and the binary is already yours or installed the standard way. It does not replace installation, does not track versions and does not fix dependencies - it is a thin layer that only tells Desktop how to call what is already installed. Expecting more of it means demanding store features from a launch map and then being surprised they are missing.
You should check the result not by the fact that "the entry was added" but along a short chain of three steps. Open the file with the palette command and make sure the binary path and arguments are correct for your OS specifically, not the neighboring one. Verify that the executable actually exists and runs by hand from the terminal - if it does not start on its own, Desktop will not bring it up either. Enable the agent on the Agents tab and restart Desktop. Only then wait for it in the selector: if it does not appear, the issue is almost always in one of these three steps, not in the ACP protocol itself.
The typical failures are predictable and almost always reduce to a swapped model. "The agent did not download" - because Desktop does not download it, the binary is installed separately. "The entry is there but the agent is not" - it was not enabled on the Agents tab or Desktop was not restarted. "Login does not go through" - the token was put in the registry instead of the environment or /login. "The file is not there" - it was looked for under the Devin name, while the path stayed .windsurf. The sign is the same in every case: the registry was taken for a store rather than a launch map for an already-installed binary. Give it back that role, and most of the "why does it not work" answers itself before you ever open a support ticket.