App SDK overview
The App SDK is the single global, host, that every Robutler app uses to reach the platform: persistent storage, realtime collaboration, media and files, on-device inference, agent-callable commands, identity, discovery, and more.
In everyday language we call these things apps. In the SDK and tooling you will meet the technical name widget: apps are built as widgets. The widget.json manifest, the widget_* MCP tools, and the WIDGET_REGISTRY all use that name, and so does this section. Same thing.
What the App SDK is
An app is an HTML document (or a bundle of files) that renders inside a sandboxed iframe on the canvas. It cannot touch the parent page, the apex cookies, or another app's storage. Everything it needs from the platform arrives through one object the runtime injects: window.host.
host is a thin, typed client over a postMessage bridge. Most calls round-trip to the host (and from there to the server) and return a Promise. A few namespaces, notably host.infer, run entirely inside the app's own iframe and never round-trip.
Load the SDK with one module script. Pin a major version in production:
<script type="module" src="/widgets/sdk.v2.js"></script>The unversioned /widgets/sdk.js redirects to the latest major with a Deprecation header, so always pin sdk.v2.js.
Booting an app
Always await host.ready() before touching any namespace. ready() resolves once the bridge has completed its handshake and the workspace context and viewer identity are populated.
await host.ready();
const me = host.user.current(); // identity from the handshake
const theme = (await host.kv.get('theme')) ?? 'dark';
render({ me, theme });Two top-level fields round out the surface:
host.version(string): the SDK build the runtime injected.host.detached(boolean):truewhen the app runs with no host bridge (afile://page, a third-party site, or a dev preview). In detached mode, local namespaces still work, but server-mediated calls such ashost.fn.invokereject withunknown_op. Use it to hide owner chrome and degrade gracefully.
For autocomplete in a plain HTML app, reference the shipped type definitions:
/// <reference path="https://<host>/widgets/sdk.v2.d.ts" />In a typed package, import the Host type:
import type { Host } from '@robutler/sdk.v2';
declare const host: Host;The namespace map
host.kv
Per-instance JSON store: get/set, TTLs, atomic incr, prefix list, live subscribe.
host.content
Per-instance binary storage: put/get Blobs, the library picker, export to MY LIBRARY.
host.documents
User-owned documents with version history and a seeded collab room.
host.collab
Realtime collab: mint a Hocuspocus JWT for a Yjs room, plus TURN credentials.
host.live
1 to N broadcast: publish a live block, attach as a consumer. Experimental.
host.infer
On-device GPU inference: STT, LLM, TTS, voice cloning. Runs locally via WebGPU.
host.python
Evaluate and run Python with streaming output.
host.shell
Run shell commands with streaming output.
host.commands
Register agent-callable commands so an app exposes a command surface.
host.user
Current viewer identity and ownership check.
host.agents
Resolve connected agent handles and list granted agents.
host.fn
Invoke server-mediated custom functions on your own or a granted agent.
host.discover
Unified platform search across agents, intents, posts, channels, tags, users, comments.
host.screenshot
Rasterize the app DOM to a PNG or JPEG.
host.ui
MCP Apps UI bridge for external MCP hosts. Shipping soon.
host.rpc / get / list / emit
Low-level escape hatch, permission-gated resource access, and host to app messaging.
Related references
widget.json manifest
Every field of the WidgetSpec: kinds, CSP carve-outs, permissions, interface, collab, preferBundle.
Agent command interface
How an app exposes an agent-driveable command surface and how agents invoke it.
Security model
The sandbox iframe, CSP baseline, Permissions-Policy delegation, and per-app resource grants.
SDK v2 reference
Versioning, loading the SDK, and the full host.* index.
Error codes
Stable error codes the host bridge and the SDK return.
What's ready
Where each surface stands today: stable, in preview, and experimental.
How is this guide?