Editor configuration

The Editor reads configuration from two JSON files in your prototype, plus a standard .mcp.json for extra MCP servers. They have different names, different loaders, and no knowledge of each other. Putting a key in the wrong one is the single most common way to spend an afternoon wondering why a setting has no effect: nothing warns you, because each loader only looks for the keys it owns and ignores everything else in the file.

This page is the map. Read the first table before you edit either file.

Which file takes which key#

Both files live in the directory you pass to the CLI (the root of your prototype), with one exception noted below.

Note One exception, and it only bites monorepos. The boot-time blocks resolve against the path you passed the CLI. The per-turn blocks (webFetch, webSearch, figma and .mcp.json) resolve against the git root instead. When your prototype is the repository, those are the same directory and this does not matter. When your prototype is a package inside a larger repository, put those blocks at the repository root, not beside the prototype's package.json.

.mcp.json is the standard MCP server file, read fresh on every chat turn. Each entry under mcpServers is an id mapping to { command, args, env }: same shape and same ${VAR} interpolation as the figma block below, which is really just a named shortcut for one of these. The id editor is reserved and refused; a figma id declared in both files is taken from .mcp.json.

Warning A key in the wrong file fails silently. readRoots inside .desde/config.json is an unknown key that the project-config parser ignores; chat inside desde.config.json is never looked for. In both cases the file parses, the Editor boots, and the setting simply does not exist.

Neither file is created for you with content. Both are optional: the Editor runs with neither. .desde/config.json is written by the Editor itself when you create or link a project, and that write preserves every other key you authored.

Note Both files are parsed with strict JSON. Comments and trailing commas are syntax errors. The annotated examples below are valid JSON; the explanations live in the tables beside them.

.desde/config.json#

Project identity, chat behaviour, and on-disk housekeeping. Read once, at boot. Changing it requires restarting the CLI.

{
  "version": 2,
  "project": {
    "id": "b6b1c0d2-4a1e-4a55-9c4a-2b0e8f6b1e33",
    "name": "Checkout redesign",
    "slug": "checkout-redesign"
  },
  "projectId": "b6b1c0d2-4a1e-4a55-9c4a-2b0e8f6b1e33",
  "projectSlug": "checkout-redesign",
  "platformBaseUrl": "https://viewer.internal.example.com",
  "chat": {
    "costCeilingUsd": 40,
    "detachedSessions": true
  },
  "conventions": {
    "useRepoConventions": true,
    "excludeFiles": ["docs/legacy-styleguide.md"]
  },
  "editor": {
    "reloadBackstop": true,
    "canvas": false
  },
  "retention": {
    "backups": { "keepNewest": 200, "maxAgeDays": 14 },
    "chatSessionTurns": { "maxTurns": 500 }
  }
}

Identity and project link#

The project block is the one exception to the blast-radius rule below: a malformed identity block degrades to "no identity" and leaves the rest of the file working.

chat#

Note maxModelCallsPerTurn and maxToolCallsPerTurn are parsed and carried through to the chat handler, but nothing currently enforces them: only costCeilingUsd reaches the agent runtime. Setting them is harmless and does nothing.

Warning There is no default ceiling. If you omit chat.costCeilingUsd, a chat session can spend without limit. A $20 default existed until 2026-08-14, when it was removed at Mo's request: the number was never shown anywhere in the product (no cost meter, no remaining-budget chip, no setting), so it only ever reached you as a refusal after a long session stopped working. A limit nobody is told about reads as a bug, not a budget. If you want a ceiling, you now have to ask for one by setting this key.

This ceiling covers foreground chat only. The small repair turn that runs when a deterministic edit cannot be applied has its own, much tighter budget that this block does not change.

conventions#

Controls whether the Editor's AI grounds itself in the instruction files your repository already has. Discovery covers five repo-root files (CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules and .github/copilot-instructions.md) plus .cursor/rules/*.md(c) and your docs/ tree.

editor#

retention#

Housekeeping for two things that would otherwise grow without limit: the per-edit backup journal that powers Undo, and the saved chat transcripts.

The backups sweep runs at boot and after each Commit.

The blast-radius rule#

This file validates as one unit. The parser returns on the first problem it finds anywhere in the file, and the caller then treats the whole file as unusable, not just the offending block.

So a typo in retention.backups.keepNewest does not merely disable that sweep. It also drops your projectSlug, your projectId, your chat settings, your conventions settings and your editor settings, all at once. The Editor still boots, in degraded mode, having printed the specific validation message as a warning line in the terminal.

Warning If a setting in this file stopped working, do not debug that setting. Read the terminal output from boot: one line names the exact key that failed validation, and that one key is disabling everything else.

A missing file is not an error. It produces one informational line saying the repository has no project association.

desde.config.json#

External read access, web access, Figma, and design systems. This file is at your prototype's root, not inside .desde/.

{
  "readRoots": {
    "production": {
      "path": "../billing-app",
      "description": "The production app this prototype mirrors."
    }
  },
  "webFetch": {
    "allowedHosts": ["docs.example.com", "raw.githubusercontent.com"]
  },
  "webSearch": {
    "enabled": false
  },
  "designSystems": [
    { "kind": "installed", "package": "@acme/ui" },
    { "kind": "npm", "spec": "@acme/icons@^2", "designSystem": "acme" },
    {
      "kind": "repo",
      "url": "https://github.com/acme/design-system",
      "ref": "main",
      "subdir": "packages/ui",
      "allowBuild": true
    }
  ],
  "figma": {
    "enabled": true,
    "mcpServer": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": { "FIGMA_API_KEY": "${FIGMA_API_KEY}" }
    }
  },
  "lanes": {
    "detach": true,
    "swap": true
  },
  "hosts": {
    "astro": true,
    "next": false
  }
}

When each block is read#

The blocks in this file are loaded at different times by different code, which is also why they fail differently.

Two consequences worth internalising. First, a JSON syntax error anywhere in this file stops the Editor from starting at all, because the read-roots loader parses the whole file at boot and a broken file is worse to fail silently than loudly. Second, webFetch, webSearch, figma, and readRoots changes made through the settings dialog all take effect on your next chat message: you do not need to restart the CLI. This last one has one exception: if you hand-edit readRoots in the JSON file directly, instead of using the dialog, the CLI does not notice until you restart it. Only writes made through the dialog (or the wizard, at project creation) update the running session live.

readRoots#

Additional folders the chat agent is allowed to read. The typical use is pointing it at the production codebase your prototype imitates, so it can see how a component is really used. A read root does not have to be a git repository. Any folder works: an exported design kit, a docs dump, a directory you unzipped somewhere.

The value is an object whose keys are the names the agent refers to, each mapping to { "path": "...", "description": "..." }.

You do not have to hand-edit this block. Once a project is open, the settings menu (the ⋮ icon) has a Reference folders item that opens a dialog to add or remove them. The launcher's per-project settings page has its own Reference folders tab that does the same thing, without opening the editor.

The New Project wizard used to have an "Add reference folders" step. It was removed 2026-08-31, to keep project creation simple. Reference folders now live only in the two settings surfaces above.

Folders added or removed through either surface apply to your next chat message. You do not need to restart the CLI. Hand-editing the JSON file directly still works, but the CLI only picks that up on the next restart.

Two separate kinds of problem can happen with a declared root, and they are handled differently on purpose. A config mistake (something you typed wrong) stops the whole session from starting, because it is a mistake you need to see and fix. An environment problem (the folder moved, or a drive is unplugged) only skips that one folder. The rest of your session, and every other read root, works normally.

Whether a root is a git repository is recorded, not required. Each root reports isGit: true or isGit: false, and that flag decides which agent tools work on it:

Read roots are read-only. Nothing in this block grants write access.

webFetch and webSearch#

Both web tools are denied by default. The reason is exfiltration: the agent can see your prototype's page content and your read roots, so text injected into a page could otherwise talk it into fetching an attacker's URL with your data in the query string. Enabling web access should be a decision, not an inheritance.

figma#

The Editor does not bundle a Figma integration. You supply any stdio MCP server you trust, and the Editor registers it for the agent so you can ask it to build a screen from a Figma frame.

Read-only is enforced at runtime, not by convention. A Figma tool call is denied unless its name starts with one of get_, list_, read_, search_, fetch_ or find_. Override that list with allowedToolPrefixes only if the server you chose names its read tools differently.

Do not put a token in this file. Write "${FIGMA_API_KEY}" and set the variable in your shell. A ${VAR} that is not set in the environment is an error, not an empty string, so a missing token fails loudly. A literal value is accepted but produces a warning, because this file is usually committed.

Warning This file can start a subprocess of your choosing. Treat it with the same care as package.json scripts: the Editor validates its shape but does not sandbox what it spawns. Content inside Figma (layer names, text, comments) is untrusted input, not instructions.

designSystems#

An array of the design systems the Editor should extract component information from. Each entry is flat, and its shape depends on kind.

Optional on any entry: designSystem, a display label, and allowBuild, a boolean that permits running the repository's own build (relevant to repo entries).

Declaring a system does no work by itself. A background pass after boot resolves declarations into extracted component data, so a fresh clone starts immediately and becomes grounded shortly after. See design-system grounding.

You often need no entries at all: installed component libraries that ship TypeScript declarations are discovered automatically.

lanes#

Turns dormant edit lanes back on. A dormant lane is one the Editor has stopped offering: its controls are absent from the workspace and the edit API refuses that kind of edit. Nothing is deleted: the applicators, and their tests, are intact and unchanged.

{
  "lanes": {
    "detach": true,
    "swap": true
  }
}

Why these two are dormant. Both applicators rewrite Vue single-file-component syntax and neither has a React equivalent, so on a React project the Editor was offering an edit that could never land. On Vue, where they work, they had gone unused. Withdrawing the offering was cheaper than building and maintaining two React applicators for a capability with no users. They are separate keys because they come back at different times: detach needs a React applicator, swap needs that and a better matching model. It currently scores candidates by prop-name overlap alone.

The icon picker is on lanes.swap deliberately. Picking an icon is a swap: it goes through the same applicator with an empty prop mapping, so it carries the same Vue-only limit and the same refusal. There is no key that separates them.

Both ends are gated. With a lane dormant, the controls are not rendered and POST /api/editor/edit and the AI-fallback endpoint refuse that kind with a message naming the key. A stale browser tab cannot reach a dormant lane.

A badly shaped lanes block is a warning, never a boot failure: an unknown lane id, or a value that is not a boolean, prints one line naming the key and is then ignored. The fallback is the dormant default, which is the shipped product, and refusing to start over a typo in an opt-in flag would be the more damaging failure. (A JSON syntax error is a different matter: it stops the boot, because readRoots parses this same file first. See when each block is read.)

hosts#

Which dev servers the Editor may start in its own process. A host that is on is booted for you by desde .; a host that is off falls back to attach mode, where you start the dev server and the Editor connects to it.

{
  "hosts": {
    "astro": true,
    "next": false
  }
}

Nuxt, React Router and Next.js became default-on on 2026-08-11. Before that date every one of them required this block to say true, and the published instructions were to use attach mode. If you have {"hosts": {"nuxt": true}} in a config file, it is now redundant and harmless. You can delete it.

Why Astro is off. Not because it fails: its boot gate passes as completely as the other three. Markup written directly in a .astro page has no applicator, so those pages are inspect-only, while .jsx, .tsx and .vue islands on the same page edit normally. That split lives inside a single project and is invisible until an edit is refused. Turning it on gives you a working in-process Astro dev server with that limit.

Setting a host to false is the escape hatch. It is how you take back control of your own dev server for a framework the Editor would otherwise boot, for a container, a custom start script, or a remote machine. The framework then behaves exactly as it did before it was flipped on, including the refusal message naming your dev command and the --attach line to paste.

A badly shaped hosts block warns and is ignored, on the same reasoning as lanes: an unknown host id lists the ids that do exist, and a non-boolean value names the key. Neither stops the boot. Note that hosts.attach is not a valid key: attach mode is reached by passing --attach <url>, never by opting in here.

The old filename#

Repositories written before the tool was renamed may have desde-composer.config.json. That name is still read, indefinitely, and never written. If both files exist the current name wins outright and the legacy one is ignored: no merging.

Warning The fallback covers only webFetch, webSearch and figma. The readRoots and designSystems loaders open desde.config.json by name with no fallback, so a repository still on the old filename gets its web and Figma settings honoured while its read roots and design systems silently do not exist. Rename the file rather than relying on the fallback.

Feature switches#

Seven switches change what appears in the workspace, through a config key or an environment variable. They do not all live in the same file, and they do not all default the same way.

All seven are read when the workspace page loads, so flipping any of them requires restarting the CLI and reloading the page.

There is an eighth switch, and it works differently from the seven above. EDITOR_REMEMBER_SCOPE_CHOICE gates a checkbox in two of the scope dialogs (iteration scope and style scope): the option to remember your choice for the rest of the session. It is hardcoded to false in the source. There is no config key for it and no environment variable. The only way to turn it on is to edit src/lib/editor-feature-flags.ts and change the constant by hand.

The canvas surface is off deliberately. It is present and intact (the components, the replay machinery, the agent's plan tools) but undertested, and turned off until it gets more investment. Expect rough edges if you enable it.

Code view, Notes and "Open in VS Code" are off for a third reason, separate from canvas and separate from the two lanes switches below. Each is a deliberate product decision, not an unfinished feature. Code view needs visual work before it ships. Notes and "Open in VS Code" were turned off outright, on 2026-08-14 and 2026-08-18.

Turning Notes off is also what makes the right rail's Comments tab honest. Comments and Notes used to render as one merged list, because the two behave identically at the UI layer. That is exactly why the tab ended up named after neither. With Notes off, that list holds only comments, so the tab can say what it holds.

Code view and Notes are gated at both ends. The client stops offering the surface, and the CLI's own API refuses it too while the switch is off (GET /api/editor/file for code view, /api/editor/notes/* for Notes), so a stale browser tab cannot reach either behind a dormant surface. "Open in VS Code" only has one end to gate: it calls no API. It sets the browser's location to a vscode:// URL built from the repo path the CLI already sends the page, so there is nothing left on the server to refuse.

The two lanes switches are off for a different reason: they work, but only on Vue, and they were unused there. lanes above has the detail. There is no environment variable for either.

Environment variables#

Most configuration is file-based. The environment variables below are the ones the Editor actually reads.

A key can also be stored from the editor's settings gear, under Anthropic API key. It lives in ~/.config/desde/llm-credentials.json (0600) and is injected into the CLI's environment at boot, so it reaches both the provider registry above and the claude binary chat spawns. An environment variable always wins; when one is set, the settings panel disables its controls rather than offering an action it cannot perform.

Note Chat itself does not use ANTHROPIC_API_KEY. It runs on the bundled claude binary and inherits whatever that binary is already signed in with. The two lanes can disagree: chat working perfectly while another action fails with Missing ANTHROPIC_API_KEY is expected behaviour, not a bug. See the quickstart.

Ports and asset paths are command line flags rather than environment variables. See the CLI reference.