widget.json manifest

Apps are built as widgets, and a widget's manifest is the single declaration the platform reads to render it, sandbox it, and expose it to agents. The shape is the WidgetSpec. First-party apps declare it in the registry; community and bundle apps declare it in widget.json (or, for a single HTML file, in a <meta name="robutler:widget"> tag, see the meta form).

The render strategy:

The workspace_items.type to insert when the app is added to the canvas. Native apps use their dedicated type (terminal, agent, daemon, ssh, python, files); iframe and projection-only apps all use content, and the content row's metadata.widgetType carries the actual identity.

The default canvas footprint { width, height } on first spawn.

For kind: 'iframe', a path under public/widgets/ (for example /widgets/snake/index.html). For kind: 'iframe-external', a fully-qualified URL. Ignored for native and projection-only apps.

A per-app CSP carve-out for first-party apps served from /widgets/*, merged into the permissive static baseline. Two keys:

This field does nothing for a bundle app. Its only consumer is composeWidgetCspHeaders in lib/workspaces/widget-csp.ts, which builds static response-header rules for /widgets/<dir>/* paths from the hard-coded WIDGET_REGISTRY at server start. An app you scaffold, remix or publish is served through the sandbox route instead, and its policy comes from _meta.ui.csp in widget.json (below). The csp and csp.frame-src / csp.connect-src keys of the <meta name="robutler:widget"> tag are parsed onto the meta record and then read by nothing on that path: publish does not store them, and no request handler consults them. Declaring them there is a silent no-op.

Keep carve-outs minimal either way: the sandbox, not the CSP, is the security boundary (see the security model), but a tight policy keeps the app's network surface honest.

The iframe allow= (Permissions-Policy) attribute, for first-party apps only. It is not hand-coded per app: the platform derives it from the app's declared permissions and the delegation rules. A community app can never self-escalate trust through allow; its sensitive features come only from per-app user grants. See Permissions-Policy delegation.

The agent-facing declaration: a description plus the commands an agent can invoke and the events the app emits. Optional. An app without an interface still renders, but it will not appear in workspace_widgets_list with anything for agents to drive. See the agent command interface for the full shape.

Each command accepts description, args, returns and streams, and nothing else: an unrecognised key (input, params, schema, a typo) is dropped without an error, leaving the command with a description and no parameter shape. The key for parameters is args. The authoring guide spells out each key.

true declares that the app uses host.collab realtime rooms. This is the gate the room-scope collab token mint checks: only collab-enabled apps may open code-based lobby rooms under their content id, so a room token cannot be turned into access to arbitrary item or workspace rooms. Set it whenever your app calls host.collab.room(...).join(...).

true serves the app from its self-contained DB bundle (the seeded *-bundle folder, via the sandbox route) instead of the static public/ entry, whenever the content row carries a folder bundle. This makes a db seed widgets enough to push an app update to a cloud environment, no CI redeploy of public/ required. It falls back to the static entry when no bundle is present. The trade-off: the mount loads through the sandbox double-iframe plus a DB read instead of a static asset.

Every bundle app (scaffolded, remixed or published) renders through the sandbox route, /widget-sandbox/<folderId>/<entry>, which injects a Content-Security-Policy into the inner document. That policy is composed on every request by composeSandboxCsp (lib/widgets/sandbox-csp.ts) from the _meta.ui.csp block of the folder's widget.json. The route reads the widget.json file child of the folder first and falls back to the manifest snapshot on the app's content row only when that file is missing, unparseable, or declares neither csp nor permissions, so editing widget.json with widget_put_files and calling __reload is enough to change the policy; no republish is involved. Script files served out of the folder carry the same policy, cached per folder for one minute (lib/widgets/folder-csp.ts). The block is validated whenever the manifest is loaded for registration, remix or publish (manifest_invalid_csp on a bad entry); the sandbox route itself parses without validating, and widget_put_files does not validate either, so a malformed entry written mid-edit surfaces at the next publish, not at reload. This block is the only CSP lever an author of a bundle app has. The type lives in lib/widgets/bundle-types.ts as WidgetCsp.

An app whose manifest has no _meta.ui.csp and none of the opt-ins below gets SANDBOX_BASELINE_CSP, verbatim:

Two consequences follow, and both fail silently from the app's point of view (a CSP violation is a console line in the browser, never an error the app can catch):

The baseline also has no frame-src (child frames are refused), no 'wasm-unsafe-eval' (WebAssembly.instantiate is refused), and no worker-src, which falls back to script-src and therefore admits a same-origin worker script but not a blob: worker.

Four arrays of bare hostnames: no scheme, no port, no path, no IP literals, no bare *, and none of the CSP tokens *, 'unsafe-eval', 'unsafe-inline', data: or blob:. A leading wildcard label is allowed (*.example.com). Each entry is emitted as https://<host> and nothing else.

Each one widens the policy by a fixed set of tokens, and nothing else. Fail-closed: an absent flag changes nothing.

One entry in _meta.ui.permissions also changes the CSP: webgpu is the compute escalation. It adds 'wasm-unsafe-eval' to script-src, worker-src 'self' blob:, blob: and data: to connect-src, and blob: to img-src. It is the only permission with a CSP effect.

Whenever any key or opt-in is present the composed policy also carries frame-src 'none' (or your frameDomains), base-uri 'self' and form-action 'self'.

An app that plays a user-picked audio file, calls one analysis API over HTTPS, and imports a library from a CDN:

That yields media-src 'self' blob: data: https:, connect-src 'self' https://api.example.com blob:, and script-src 'self' 'unsafe-inline' https://esm.sh. The microphone entry is what lets getUserMedia run once the user grants it; it plays no part in the policy above.

_meta.ui.permissions is the Permissions-Policy list: the browser features the app wants delegated into its iframe through the allow= attribute. It accepts camera, microphone, display-capture, geolocation, clipboard-write, fullscreen, webgpu, xr-spatial-tracking and files (a bridge-gated platform capability that is never emitted into a Permissions-Policy), and rejects anything else with manifest_invalid_shape. It has no effect on the CSP, with the single webgpu exception noted above.

The two rails are easy to conflate because both look like "what the app is allowed to do", and because a granted feature is visible in the workspace item: a community app cannot self-grant a sensitive feature, so microphone reaches the outer iframe's allow= only after the user approves a per-instance grant, and that grant is stored on the item's state. Seeing microphone there means exactly one thing: getUserMedia({ audio: true }) is permitted in this instance. It says nothing about whether the app may fetch a host, open a socket, or play a file; those are CSP questions, answered only by _meta.ui.csp. An app that records from the microphone and then cannot play the recording back is missing csp.media, not a permission. See Permissions-Policy delegation for how grants flow.

A single HTML file can be an app by dropping a <meta name="robutler:widget"> tag. Two forms, which can be mixed (per-field tags win over the JSON form for keys they cover):

Recognized fields: name, title, description, size, minSize, maxSize, mobile, icon, kv, author, version, permissions, kind, fileHandlers, events, commands (top-level or nested under interface), and csp.frame-src / csp.connect-src. The kv field is a private-storage disclosure (surfaced in the install confirmation), not an enforced allowlist.

In the JSON form each command is an object with description, args, returns and streams; other keys are ignored silently (see interface). The per-field robutler:widget:commands and robutler:widget:events tags take only name:description pairs, so a command with parameters has to use the JSON form.

This declaration is not read live. When widget_scaffold registers the app and on every widget_publish, the platform reads it from the entry HTML and stores the resulting interface, size, minSize, maxSize, mobile and fileHandlers on the app's content row, and folds the interface into the bundle's manifest snapshot as _meta.ui.interface, which is what the canvas and workspace_widgets_list resolve. widget_remix copies the source app's snapshot unchanged, so a remixed app carries the original's interface until it is published. The csp keys are not stored and not enforced on this path. The sandbox policy for a bundle app comes only from _meta.ui.csp in widget.json, described above.