Manifest reference

Every field group, and what it's for. If you know the shape you want but not its name, scan the right-hand column.

Top level#

permissions#

Each entry is "<METHOD> <path-glob>", where * matches exactly one path segment: one grammar for both halves, because the install dialog, the gate and the usage ledger all read it. The two lists are separate because the halves run as different principals: the UI acts with the owner's session, the backend with a token minted for exactly this extension, and a grant to one must never quietly widen the other.

• sandbox: the routes the UI half may call. Every door in api.sandbox is checked against it, so a call to anything not covered throws. That includes the typed rpc client, which resolves to a method and a concrete path and is gated on that exactly as request and json are. This constrains use of the published extension API; a browser bundle still shares the app's DOM, storage, globals and network access.
• daemon: the routes the backend half may call through api.daemon, enforced daemon-side against its minted token.

"permissions": {
    "sandbox": ["GET /panels", "POST /panels/*/start", "GET /memory/file"],
    "daemon": ["GET /capabilities/*/connection"]
}

Keep both as narrow as the feature needs. These lists are what a reviewer reads to understand declared daemon API use, not a complete confinement boundary for browser or process code. The HTTP API page is what the routes are. An extension's own namespace, /x/<id>/…, needs no entry on either list: its backend is its own code from the same approved checkout.

server: the backend half#

A manifest server entry names a prebuilt, self-contained node ESM bundle exporting activateServer(api, context). That is the extension's backend: real server code of its own, for the features a browser bundle can't carry: a client library for somebody else's API, work that must outlive the tab, state assembled from workspace files.

• Its own route namespace. The backend serves /x/<id>/…, proxied by the daemon through its ordinary auth, so it does not receive the caller's session credential. It does receive its own extension token and workspace root for daemon work; that reach is part of the source audit. The extension's UI calls its own namespace freely because both halves are code from the same approved checkout.
• One supervised host process. Every enabled backend runs in the daemon's single backend-host process, not in the daemon itself. Loaded code can't be unloaded, so the off switch, an update and a live edit all work the same way: the host restarts. The restart is the reload.
• Declared reach back into the daemon. The backend's calls into the daemon's own routes go through api.daemon and are gated by permissions.daemon, with a per-extension token: the same honesty rule as the UI half, enforced against a different principal.
• Self-contained by construction. The installed checkout has no node_modules and the host provides no import map, so everything except node builtins must be bundled in.

The backend API surface includes routes.mount, api.daemon and workspaceRoot. It is documented on the Host API page. A backend requires engines.intentic of ^2.1.0 or wider.

contributes.views#

Pick the surface by what the view is about. The rail is a place people act from and its slots are permanent, so earn one. A view about the box itself (its logs, its consumption) belongs on the Sandbox hub, where things are inspected occasionally rather than worked in.

contributes.files#

An intentic workspace is file-first: the agent edits files directly, out of band from every HTTP route. Declaring the files behind your view is what gets you into the daemon's change push instead of polling for it.

Narrow paths matter. A broad prefix costs every connected browser a refetch on every matching write, and a write-heavy path turns that into a request storm.

contributes.viewers#

A renderer for a file type. The host resolves the open file, fetches its content, and renders your component with it.

contributes.documents#

A per-directory document family: your provider marks the Workspace-tree rows it can explain with an icon, and the host opens your component as a tab beside the code. This is how the commit graph sits on every repository row, and how a package's architecture page sits on the packages that have one.

Only the id and label are declared. A viewer takes files over and a command can claim a global shortcut, so those are approved field by field. A document provider takes nothing over: it adds an icon to rows it has something for, and every such row is evidence the owner can see. So the manifest gates whether you may mark up the tree at all, and the per-row wording stays with your provider, which is the only thing that knows what it found.

contributes.commands#

A global shortcut is consequential, so like the title it's declared here and the host binds only what was approved.

contributes.settings#

Typed settings the host renders into the Settings page and persists daemon-side, shared across all the owner's browsers.

Settings live on the daemon keyed by publisher.name, so they outlive a re-clone, an update, or a remove and re-add.

contributes.capabilities#

A whole third-party integration expressed as data, with no code. It produces a real capability card in the app: a "+" tile, a config form, credentials stored as secrets, environment variables in the agent's shell, and a SKILL.md cheatsheet that teaches the agent to use the tool.

You contribute a card, never a handler. The machinery that acts on a capability lives in the daemon, because some of it grants real privilege: putting the sandbox on a private network, running it privileged, changing what an agent may do on somebody's personal computer. So the four kinds below are the ones whose daemon-side behaviour is entirely generic over your data; a manifest naming any other kind is rejected at install.

"capabilities": [
    {
        "id": "linear",
        "kind": "cli",
        "catalog": {
            "name": "Linear",
            "logo": "linear",
            "description": "Read and file issues from the agent's shell.",
            "category": "Project management",
            "guide": {
                "url": "https://linear.app/settings/api",
                "linkLabel": "Create a personal API key",
                "steps": ["Open Settings → API", "Create a personal key", "Paste it here"]
            }
        },
        "fields": [{ "key": "apiKey", "label": "API key", "secret": true }],
        "env": { "LINEAR_API_KEY": "${apiKey}" },
        "skill": "skills/linear/SKILL.md"
    }
]

This contribution point covers the most ground: one entry plus two files adds an integration to the product.

One field flag carries a security rule. A field marked totp (declared with secret) holds the seed an authenticator app would hold. So unlike an ordinary secret it never enters the agent's environment either. The daemon mints the six-digit codes on demand and only those cross, each dead within its period; an env template that references a totp field fails to parse rather than handing the agent the second factor itself.

contributes.processes and contributes.listener#

A process is a long-lived background program the daemon supervises. Pair it with a listener and you have a realtime event source that can wake the agent, exactly how the Discord and IMAP integrations work.

"processes": [
    { "name": "gateway", "command": "node dist/gateway.js", "port": "auto", "autoStart": true }
],
"listener": {
    "provider": "linear",
    "events": [
        { "type": "issue_created", "label": "Issues created" },
        { "type": "comment_added", "label": "Comments added" }
    ],
    "automation": {
        "label": "Linear",
        "channel": { "label": "Team ID (optional)", "placeholder": "all teams" },
        "starterPrompt": "Linear events arrived. Triage each issue or comment and use the Linear capability when a response or update is needed."
    }
}

The daemon holds no connection to your provider; your process does. It gets a provider-scoped control surface to reconcile state, dispatch a wake, and report status or failure.

contributes.agent and contributes.bin#

These two are how an extension changes what the agent can do rather than what the owner can see. Both are composed per turn, so they take effect from the next one, with no reload.

contributes.environment#

A Dockerfile fragment baked into the sandbox image overlay, for when your tool has to actually be installed: a database client, a media encoder, a language runtime.

FROM and privileged directives are rejected. An extension can install tools but can't claim container privileges or swap the base image. The owner approves the composed overlay and rebuilds out of band, so this is the one contribution that applies on the next image rebuild rather than immediately.

When each contribution takes effect#

The Extensions tab states this per extension, so nobody has to guess why a change hasn't landed yet.