Skip to main content

Trust & Capabilities

Daintree plugin permissions: twenty-four capability tokens, first-use consent, terminal-screen access, project targeting, plugin agent tools, scope checks, audit records, project trust, and execution boundaries.

Updated
Reviewed

A plugin declares what it needs in its manifest's capabilities array. This page is the full account of what that declaration does, and just as importantly, what it does not do. If you are deciding whether to install a plugin, or writing one and wondering how much friction a token buys, this is the page to read.

The contract in one line

Capabilities are disclosure-first with host-side policy effects. The host does not sandbox plugin code. The declaration is surfaced in the plugin manager, it drives host-derived danger classification on every action the plugin registers, it gates several host APIs at runtime, and it caps how dangerous a plugin's MCP tools are allowed to be. It is not an enforcement boundary against malicious code. It is an honest, machine-readable description of what a plugin claims to need, which the host uses to apply proportional friction at the points that matter.

The twenty-four capabilities

Eight are classified as high-risk. They can raise action danger to confirmation and allow a higher ceiling on plugin MCP tool danger. Per-command requires narrows which declared capabilities inform that action classification. Six tokens also ask the user the first time a host API uses them (just-in-time consent), agent:launch-preset asks once per preset, and three more do nothing until the user turns on a per-plugin switch.

TokenWhat it gates or disclosesHigh-risk
fs:project-readRead files in the current project worktree. Gates host.fs reads and PDF render inputs by the class of the root a path resolves into.
fs:project-writeWrite in the project worktree. Gates host.fs writes, PDF output, database backups, and a writable "project" database. First use asks for consent.yes
fs:user-data-readRead under the Daintree data directory or elsewhere in the home directory. Gates host.fs and host.system.
fs:user-data-writeWrite there, including the plugin's own data directory. First use asks for consent.yes
network:fetchOutbound HTTP. Attenuated by a network scope. Also required, with artifact:store, by host.artifacts downloads and uploads.
agent:invokeSend prompts to agents from plugin code. Disclosure and danger input; gates no host API.yes
agent:readObserve agent state. Gates host.getAgentState, its subscription, terminal lifecycle events (metadata only, never a command, title, or output), host.agents.list, host.setTerminalStatus, the agentWaiting event route, and, for app-wide installed and built-in plugins only, host.agents.listAll and onDidChangeAllAgents.
agent:registerRequired for contributes.agents: the schema rejects the array without it.yes
agent:inputhost.sendToActiveAgent, host.sendToAgent, and host.agents.interrupt, sendKeys, and submit. First use asks for consent.yes
agent:launch-presetLaunch an agent on one of the user's presets with host.dispatch("agent.launch", { agentId, presetId }). Declaring it enables nothing: each preset asks once, and the grant ends when that preset's content changes, because one preset may turn on bypass mode.yes
terminal:readhost.terminals.readScreen: a terminal's current screen as plain text. First use asks for consent, and the prompt says plainly that the plugin can read what your terminals show.
git:readRead git state. Gates host.git.status and diff.
git:writeMutations. Gates host.git.add and commit. First use asks for consent.yes
clipboard:readhost.clipboard.readText. Text only: there is no image, HTML, or file-list read.
clipboard:writewriteText up to 8 MiB and writeImage up to 20 MiB (8 MiB when the window driving the project is on another machine, whose clipboard asks its own permission).
shell:exechost.process.spawn. A managed spawn without the declaration rejects; first use also requires consent.yes
socket:connectLocal Unix sockets and Windows named pipes, the Docker socket being the motivating case. Disclosure only.
mcp:exposeRequired for contributes.agentMcp and host.mcp.registerTools. Exposes nothing by itself: the user chooses per project whether agents get the tools.
project:dispatchhost.dispatch with an explicit projectId from an installed plugin, behind the user's Allow project targeting switch for that plugin. No first-use prompt: the switch is the whole grant.
host:dispatchhost.remoteHosts.list(), host.dispatch with a hostId, and host.agents.interrupt, sendKeys, and submit with a hostId (which also need agent:input), from an app-wide installed plugin, behind the user's Allow host targeting switch. Each remote host then applies its own consent and confirmation rules. A project-bound plugin can never use it.
panel:focus-readhost.onDidChangeFocusedPanel: the kind of panel that has focus, whether it is an agent, and its worktree, never its id, title, URL, or content. Disclosure only.
notification:oshost.notify({ os: true }), a banner from the operating system. Off until the user turns on Allow OS notifications for the plugin.
artifact:storehost.artifacts: hold large files in the host's artifact cache, importing a scoped or chosen file, downloading or uploading a provider file, or playing one in a view. Counts as a sensitive read in the compound lattice, because the person can choose any file.
preview:inspectRequired by contributes.elementPickerProviders: read the DOM and runtime of a previewed page for the Element Picker. Disclosure only.

For filesystem gates, the class of the root a path resolves into decides, not the token's name: a literal home-directory path reaching into a project is still user-data class. The first-use grant for writes is keyed on the strongest write capability the plugin declares.

socket:connect is deliberately outside the high-risk set even though what it reaches can be powerful. The host has no interception point for raw socket connections, so treating it as gated would imply enforcement that does not exist. It is disclosed so the manager can say "connects to the Docker socket" instead of showing a bare token.

The field is named capabilities. An older permissions key is not accepted.

{
  "capabilities": ["git:read", "network:fetch"],
  "scopes": {
    "network": { "allowedUrls": ["https://api.linear.app/"] },
    "fs": { "allowedPaths": ["${worktree}/.linear"] }
  }
}

What a declaration actually does

It raises action danger

By default, when a manifest holds any of the eight high-risk tokens, its actions are raised to a confirm classification, regardless of what the action itself declared. The host may only raise, never lower: a plugin cannot declare its way out of a prompt. That classification gates the confirm dialog, eligibility for the recently-used rail, and repeat-last-action.

This is host-side policy on Daintree's own action system. It does not stop the plugin executing code.

Raising every action for one capability used to be crude: a plugin needing shell:exec for a single command put a destructive confirmation on its "open the panel" command too. Per-action capability intent fixes that without the dishonest workaround of dropping the capability.

{
  "id": "open-panel",
  "title": "Open Panel",
  "description": "Opens the tools panel.",
  "category": "Flutter Tools",
  "kind": "command",
  "danger": "safe",
  "requires": []
}
  • Omit requires and nothing changes: the whole manifest is consulted, as before.
  • requires: [] declares that this command exercises no capability, so it stays one click even in a plugin holding shell:exec.
  • requires: ["git:read"] consults only those capabilities, for both the high-risk set and the compound lattice.

Three things it does not do. It grants no access: host APIs still gate on the manifest's capabilities at call time, so naming a token here neither adds nor removes runtime authority. It cannot lower a self-declared confirm. And every entry must appear in capabilities: naming one you did not declare fails the command's registration outright, so a typo surfaces at load rather than quietly reverting to the old behavior.

The compound lattice

Individually benign capabilities can be dangerous together, and that combination is precisely what pure disclosure cannot see. The host raises danger for two compound classes even when no single token triggers:

  • Exfiltration: a sensitive read (agent:read, terminal:read, git:read, artifact:store, or a filesystem read) paired with an unconstrained sink (shell:exec or network:fetch).
  • Remote-controlled mutation: network:fetch paired with a local write or a shell sink.

A non-empty network allowlist attenuates the compound elevation based on declared intent. It is not proof that requests only reach that host: the host does not intercept raw network calls. Filesystem scope does not suppress the high-risk classification of writes.

Scopes, by how much they bind

Scopes live in a top-level scopes object, not per capability. They do not all bind equally, and the difference is worth knowing before you rely on one.

ScopeStrength
scopes.fs.allowedPathsRuntime-enforced for host.fs, host.git, and host.system. Every path argument is realpath-resolved and contained; a traversal or a symlink that escapes rejects. Supports project and worktree tokens with optional sub-path suffixes.
scopes.network.allowedUrlsLive, and mostly advisory. It suppresses lattice elevation. It does not block a plugin's own fetch, which the host cannot intercept, but host.artifacts downloads and uploads are refused outside it, redirects included.
scopes.socket.allowedPathsPurely advisory. It exists so the manager can name what the plugin connects to.

Wildcards are rejected at the schema boundary, as are credential-bearing and private-host URLs. A misspelled scope bucket is a manifest error rather than a silent no-op.

How enforcement surfaces

The host-mediated APIs fail with prefixed errors so a plugin (and the renderer hook wrapping it) can discriminate.

PERMISSION_REQUIRED:  the capability was never declared, or the user denied consent
PATH_NOT_ALLOWED:     the path resolved outside scopes.fs.allowedPaths

The honest limit: this gates the sanctioned path only. A plugin's main is un-sandboxed Node running in its worker, and it can call node:fs directly. host.fs gives a contained, audited route; it does not seal the un-mediated one.

Declaring a high-risk capability answers "may this plugin ever do X". It does not answer "has the user agreed to it doing X now". For the capabilities where the gap matters, the first call raises a prompt.

Six capability tokens are gated this way: shell:exec, fs:project-write and fs:user-data-write, git:write, agent:input, and terminal:read. The prompt names the plugin, the capability, and the plugin's full declared capability list. You can choose Allow and remember or Deny. An approval pins the grant, so later calls run silently; denying, or leaving the prompt unanswered for five minutes, throws a permission error into the plugin. Concurrent first-use calls are coalesced onto one prompt, so a plugin firing several spawns at once raises one dialog rather than a stack. Built-in plugins skip the prompt: they are app-bundled first-party code. Grants are held per plugin instance, so one project's grant never answers for another project's copy of the same plugin.

project:dispatch, host:dispatch, and notification:os have no prompt on purpose: the per-plugin Allow project targeting, Allow host targeting, and Allow OS notifications switches are the whole grant. With a targeting switch off, an unattended plugin fails fast rather than waiting on a dialog; with the OS-notification switch off, the notification still appears in Daintree, just not as an OS banner. agent:launch-preset prompts per preset rather than per capability, naming what that preset turns on.

Archive replacement and uninstall revoke grants. An install that replaces a plugin with a different archive purges both the capability grants and the MCP consent pins, so new code never silently inherits the previous version's approvals. Reinstalling a byte-identical archive keeps them, since no code changed; that needs a recorded digest to compare and does not apply to a dev-linked copy, or to an instanceMode: "project" package, whose instances' grants are purged by any replacement and not offered back. After a replacing install, Daintree offers back in one dialog the capability grants the new version still declares, including the targeting, OS-notification, and attention-view switches; that is a fresh approval, and declining leaves them off. Link-opening site grants and per-preset agent:launch-preset grants are never offered back, and MCP tool pins are not either. Cloud provider consent is separate and survives an update that leaves the providers' declarations unchanged (see below). Confirming an update installs exactly the archive whose manifest the confirmation previewed: the install is bound to that archive's hash. Uninstall purges grants too, which means reinstalling the same plugin name re-prompts rather than resuming where it left off. Known project plugins follow a different update contract: source and build changes reload without a new folder approval. Revoking project trust purges that project's instance grants; an individual mute preserves them. See Project Plugin Trust & Management.

A cloud provider holds the person's cloud credentials, decides which machine Daintree connects to, and vouches for that machine's identity. No capability token says any of that, so a plugin's provider gets an account only after a consent of its own. Before any credential field is shown, Connect account asks Allow … to use your cloud accounts?, naming the plugin and its id, and says the plugin receives the credentials entered (including when they are only checked), chooses the machines Daintree connects to and vouches for their identity, and creates machines that bill the person's own account. Cancelling sends and keeps nothing.

One agreement covers every cloud provider the plugin declares, and is tied to a fingerprint of those declarations: credential fields, capabilities, API origin and createReplay. An update that changes any of them, or adds or drops a provider, pauses the plugin's accounts until the person allows it again with Review access in Settings → Hosts; changing only a provider's name, description or its apiKeyUrl, dashboardUrl and docsUrl asks nothing, while a tunnel's installUrl counts. Review access can't bring back a provider the plugin dropped, and an account's saved credentials stay bound to the API origin it was connected with. Unlike capability grants, the consent survives an update that leaves the declarations alone. Uninstalling forgets it; the plugin's accounts stay, paused, and the Plugin Manager asks whether to keep or remove them (daintree-plugin uninstall keeps them). The trust ceiling doesn't move: the worker is a full Node process and keeps whatever credentials it is handed; the consent decides what Daintree hands over and when.

Plugin MCP tools

Plugins reach MCP in two directions, with two different trust models. A plugin can ship mcpServers that Daintree runs and calls, and it can serve its own tools to the agents in your terminals through agentMcp. Both are covered below.

Plugin-shipped MCP servers

An installed or builtin plugin can contribute MCP servers. A project manifest can declare one only when an agentMcp endpoint's source bridges it; that server is reached only through the endpoint's project-bound agent access, never through the surface described here. The same rule applies to an installed package with "instanceMode": "project". An app-wide plugin's server tools become callable through the plugin MCP surface that Daintree and its Assistant use. The server process starts from the plugin worker's environment allowlist, including proxy and CA settings, plus its manifest env, not from Daintree's own environment, so tokens in Daintree's environment do not reach it. That tool surface is the sharpest edge in the whole system (tools a model invokes on its own), so every call passes through three stages: consent, audit, rate limit.

Consent is trust on first use. Each tool is pinned by a fingerprint over its raw description bytes, its input schema, and its tier-influencing annotation hints. The first call prompts even for a D0 read-only tool. Remembered approvals are reused while the fingerprint matches, and re-prompt with "this tool changed" framing when it does not:

  • the raw description bytes mutated, which is the rug-pull case, flagged regardless of whether the rendered text looks identical;
  • the input schema mutated, so the call surface changed;
  • the annotation hints mutated, so the advertised danger surface changed.

The prompt shows an ANSI-stripped description and, at higher tiers, a redacted args preview. Raw description bytes never reach the renderer; they are hashed and discarded. A user can approve once without pinning, approve and pin, or reject. An abandoned prompt times out after five minutes and fails closed, recorded distinctly from a deliberate refusal so an operator can tell them apart.

The tier cap is where the manifest binds the tool surface. Calls are classified D0 (read-only) through D3 (catastrophic, reserved). A plugin's declared capabilities cap the tier its tools may reach: a plugin that declared none of the eight high-risk tokens cannot have its server reach D2, "shared-state mutation", merely by advertising a destructive hint. A call above the cap is denied, not downgraded: a downgrade would let the model present a mutation as read-only and slip past the audit narrative.

Every dispatch is written to a per-record audit ring, and every server has its own token bucket: a burst of 20 with sustained refill of one per second, keyed per plugin and server so one plugin's tool spam cannot throttle another's.

Agent tools

A plugin's agentMcp tools, and the read-only database_schema and database_query tools the host adds for its declared databases, reach agents through one MCP server per plugin. Two separate decisions stand between a plugin and an agent:

  • Declaring mcp:expose is disclosure. It is listed in the Plugin Manager, the manifest is refused without it, and host.mcp.registerTools throws without it. It exposes nothing.
  • Exposure is a per-plugin, per-project choice in Project settings > Plugins > Agent tools: Off (the default), Read only (the database tools), or Read and write (the plugin's own tools as well). An endpoint that declares tool groups is answered group by group instead, and the setting shows only the choices that apply to the plugin. An installed plugin's choice can be made the default for every project, and a project's own choice still overrides it. Installing, enabling, or trusting a plugin never gives agents its tools.

A repository can set defaults in .daintree/mcp.json, but only for the project plugins it ships, which run only after you trust the folder anyway; it can never turn on an installed plugin, because that would let any clone read your own plugin data through your agents. Your answer is stored in Daintree's own store, outside the repository, and beats the repository's default in both directions. Answers are keyed by plugin instance. Lowering access revokes every live credential it no longer covers, and running agents lose the tools on their next request; raising it reaches agents launched afterwards. There is no per-call prompt: the access setting is the gate.

Each agent launch gets its own credential per plugin with access: 32 random bytes bound to one plugin instance in one project and to the tools its access allowed at launch. Daintree keeps only a digest and hands the bearer over in a Daintree-owned file readable only by you, or in the terminal's environment, never on the command line, in the repository, or in your agent's own configuration. It is revoked when the launch ends, the plugin unloads, or access is lowered. A leaked credential can call that one plugin's tools, as that one project, until then; it cannot reach Daintree's own MCP tools, another plugin, or another project.

Two limits are worth knowing. A plugin cannot vouch for its own tools' safety: it may declare cautious MCP hints only, and a roster claiming a tool is read-only, non-destructive, or closed-world is rejected, because agent clients may ask less for tools described that way. And an app-wide installed plugin can only have local databases, one file shared by every project, so giving it database access in one project lets agents there read what it stored for all of them; the Agent tools setting says so beside the choice. The host caps the size of tool names, descriptions, schemas, and results, not their content: a tool result is the plugin's data, and an agent can be misled by it.

The audit trail

Plugin activity is recorded in a structured, persisted ring buffer: 500 records by default, configurable between 50 and 5000. Three kinds of event land in it:

  • Action dispatch: a plugin-contributed action running through the action service, with its source and danger classification.
  • IPC invoke: a call into a plugin's own registered handler. Both success and failure are recorded at the dispatch boundary, so a benign-looking invoke cannot run unobserved, and a trust-check rejection on the raw channel is recorded too.
  • Decoration failure: a file-decoration provider that rejected or exceeded its budget. Successful pulls are not audited.

Writes through host.fs, git mutations, process spawns, and successful host.system calls are recorded as well. Privacy is the default: args are stored as a SHA-256 digest of the redacted summary, and a plaintext summary is written only when a developer explicitly opts in, capped so one oversized payload cannot bloat the store.

Scrubbed logs

Everything a plugin writes through host.logger is run through Daintree's secret scrubber before it reaches either sink: the per-plugin ring buffer that feeds shareable diagnostics, and the console mirror. Scrubbing happens before the line-length cap, so a secret straddling the truncation boundary is fully redacted rather than bisected into a fragment the scrubber would no longer match.

The blocklist

Daintree fetches a small remote blocklist at startup: plugins it refuses to load, matched by name and version range. It is a security response for a known-compromised plugin, not a deprecation mechanism.

The list is cached on disk with a six-hour freshness window, so an entry propagates to running installs within hours rather than a day and a stale list is still enforced offline. When a cached list exists, startup enforces it immediately, even if stale, and never waits on the network: a refresh runs in the background, and when it arrives anything it newly blocks is unloaded. Only a first start with no cache at all waits for the fetch, with an eight-second ceiling. A failed fetch keeps the cached entries; with no usable cache, it fails open. Failure to refresh does not clear an existing block. A blocked plugin still appears in the manager, with the reason shown, rather than vanishing.

Asset containment

A plugin's static assets and view bundles are served over a dedicated plugin:// protocol rather than from disk paths or a bundled web server. The authority is an opaque per-load value minted by Daintree; the path resolves against that plugin's installed directory, is realpath-contained, and rejects anything that escapes the root. There are no directory listings, and a request naming an unknown or disabled plugin returns a 404 without disclosing whether the id exists.

The scheme is registered as a hardened first-party scheme: standard, secure, and explicitly without CSP bypass. Because a plugin view is lazy-imported as a module, plugin: appears as a narrow allowance in the app's own content-security-policy script directive. That narrow directive expansion is the minimum surface that makes plugin views work; the alternative of exempting the scheme from CSP entirely was rejected outright.

Process isolation

User-installed and project-plugin main entries run in utility workers with separate module realms and process crash isolation. Builtin entries activate in the main process. React view components are imported into Daintree's renderer, outside the worker, and use the host's React instance. The worker boundary does not isolate every part of a plugin or guarantee that a view cannot affect its renderer. Unloading discards worker memory and terminates the processes the plugin started, including their own children; settings, storage, databases, and saved panel state can survive.

The worker, the processes it spawns through host.process, and its MCP servers all start from a short environment allowlist (PATH, HOME, temp directories, locale, time zone, shell and user names, and the Windows essentials; the worker and MCP servers also get proxy and CA settings), not from Daintree's own environment, so API tokens in Daintree's environment do not leak into plugin code by default. This narrows an accident; it is not a boundary, because the worker can still read files your account can read.

It does not buy a security boundary. The worker is a separate process, not a sandbox: the plugin's code still runs with the full privileges of your user account, and the host does not intercept its Node calls. Treat the isolation as a reliability property and the capability list as a disclosure property, and you have the model right.

On a remote host the split crosses machines. A host plugin's main entry runs on the host, as your user there, and capability prompts appear in the window that has control, with the answer stored on the host. Its React views load from the host and run in your window, with the access Daintree has on this computer, which is why Daintree asks Run "…" from studio-01 on this computer? before a view first runs, and again when the host changes the plugin's code. See Plugins From a Host.

Runtime limits

Read these limits alongside the specific host API gates above.

  • No runtime sandbox. A plugin's main can call node:fs, spawn subprocesses, and open sockets regardless of what it declared. The capability list governs declared intent through host-side policy; it is not a kernel of enforcement against arbitrary code.
  • No signing and no publisher identity. Daintree verifies a plugin's integrity (a SHA-256 hash over the archive bytes, persisted in the provenance record and used for update detection) but not its authenticity. Archives carry no signature and there is no publisher-identity system. Verify the source as well as the transport; a hash alone does not authenticate it.
  • Installation prompts depend on the route. A .dntr archive opened from the operating system, a URL install (including a daintree://plugin/install link), and a community catalog install show a pre-install preview with identity, capabilities by severity, and contributed recipes; a URL or catalog install then installs only the archive that preview was read from. Drag-and-drop, file-picker, CLI, and sideload routes show no such preview. The URL UI warns about HTTP, but the shared fetch guard still requires HTTPS. Project plugins have their own folder trust banner. None of these previews authenticates the publisher or sandboxes the code.
  • Secrets use the OS keychain, or are not saved at all. Settings declared type: "secret" are encrypted at rest through the platform keychain and stored as a ciphertext envelope. Where no keychain backend exists (typically a headless Linux host, or a Linux session whose only backend is Chromium's built-in text store), Daintree refuses to save the secret rather than writing it in plaintext, and the field says why; use environment variables or the CLI's own login on that machine instead. A user or local value that an older version stored as plaintext stays until you replace or delete it; when secure storage is available, the form flags it Stored as plaintext and re-saving moves it into encrypted storage. Old project-scoped secrets in repository files are ignored, not migrated or deleted, so remove them yourself. One caveat remains: a keychain secret is still readable by anything running as your user.
  • A locked keychain needs a restart. After a Keychain or Keyring gives Daintree no key for the current session, secret writes are refused and the field tells you to restart. A keyring prompt left unanswered times out after 60 seconds. The settings form checks secret presence without decrypting values. The Linux release update adds this recovery path and uses asynchronous encryption so an unlock prompt does not hold the app's main thread.
Warning
Prefer scoped, short-lived, or read-only tokens for anything a plugin stores. Do not put a credential in a plugin setting if it must survive a compromise of your logged-in session.

Reading a plugin before you install it

Given all of the above, the practical questions are short:

  • Do the declared capabilities match what the plugin is for? A theme packager asking for shell:exec is suspicious. A forge integration asking for network:fetch is expected.
  • Is the network scope narrow? An unconstrained network:fetch paired with any read or write capability is the compound class worth pausing on.
  • Where did the archive come from? Review the recorded file or URL source and the corresponding repository. A local file also needs a trustworthy origin.
  • Can you read the source? Sideloading from a repository you have inspected is the strongest position available in the current model.

Trust in a plugin's code is the user's responsibility. Install from sources you trust, and inspect plugins that request broad capabilities. Daintree's job is to make that judgment possible, not to make it unnecessary. See Security & Privacy for how the same reasoning applies to the rest of the app.

Audited implementation: high-risk tokens, danger derivation, capability consent, worker activation, and archive preview. Links are pinned to the October 13, 2026 audit.