Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
Plugin UI SDK (window.clerum)
A plugin can ship a web app that the Desktop App shows under Apps. Inside
that app, the Desktop App exposes a small JavaScript API on window.clerum. The
app uses it to ask the user for access to their information (who they are,
their team, agents, contexts, MCP servers, shared files), to follow the app's
light or dark theme, and to send desktop notifications.
There is no npm package for this API. Your app's JavaScript calls
window.clerum directly, and the Desktop App injects it.
SDK version 1.0.0, wire protocol 1.
Where it is available
The API on this page is injected only into a sandbox UI embedded in the
Desktop App: the web app a recipe declares in spec.ui. It is not available
in the Control UI, in Profile UI, in a normal browser tab, or in a recipe's
backend workloads. The Desktop App's own interface has a separate, trusted
window.clerum bridge with a different shape (see
Desktop App § Electron security posture);
plugins cannot reach it.
A recipe declares one sandbox UI by pointing spec.ui.workloadRef at a
type: deployment workload and naming its HTTP port. See
WorkflowRecipe § Sandbox UI (spec.ui)
for the fields and validation rules, and the
recipe authoring guide
for build and image requirements.
The Desktop App loads the UI through rpc-proxy into its own
WebContentsView and attaches the SDK as that view's preload script. Each
mounted UI is registered with the Desktop App under the plugin id
<recipeNamespace>/<recipeName>. The plugin never says who it is; the Desktop
App derives the id from the view that sent the call.
Always feature-detect, so the same UI still works outside the Desktop App:
const sdk = window.clerum && window.clerum.sdk
if (!sdk) {
// Not running inside the Desktop App. Render without the SDK.
}
Response shape
Every SDK method except on and onOauthCompleted returns a promise that
resolves to one of two shapes. It does not reject for a refused call.
type PluginSdkResponse<T> =
| { ok: true; data: T }
| { ok: false; error: { code: string; message: string; retryable: boolean } }
message is safe to show to the user. It never carries upstream error bodies.
retryable is true when the same call may succeed later without the user
doing anything (for example, after a rate limit).
API surface
clerum.sdk
| Member | Returns | Notes |
|---|---|---|
sdk.version |
'1.0.0' |
String constant. |
sdk.protocol |
1 |
Number constant. |
sdk.capabilities() |
{ capabilities: string[], version: string } |
The capability ids this Desktop build implements. Use it to degrade gracefully on an older Desktop App. |
sdk.requestPermissions(ids) |
{ granted: Record<string, boolean>, all: boolean } |
Asks for 1 to 8 capabilities in one consent prompt. Shows a prompt only for ids that are not already granted. A partial grant is a normal result, not an error. |
sdk.permissions(ids?) |
{ granted: Record<string, boolean> } |
Reads grant state without prompting. With no argument it reports every capability. Up to 8 ids when you pass a list. |
sdk.on(callback) |
an unsubscribe function | Receives events. |
requestPermissions and permissions return invalid_request for an empty
list (for requestPermissions), more than 8 ids, a duplicate id, a non-string
entry, or an unknown capability id.
Capability methods
Each method below sends one capability call. If the capability needs consent
and the user has not granted it yet, the call itself opens a one-row consent
prompt. Call requestPermissions first so the user sees one prompt for
everything your app needs.
| Method | Capability id | Consent |
|---|---|---|
clerum.identity.get() |
identity.read |
Yes |
clerum.org.get() |
org.read |
Yes |
clerum.agents.list() |
agents.read |
Yes |
clerum.contexts.list() |
contexts.read |
Yes |
clerum.mcp.list() |
mcp.read |
Yes |
clerum.gfs.list({ drive?, resourceId?, cursor? }) |
gfs.list |
Yes |
clerum.gfs.read({ uri, as }) |
gfs.read |
Yes |
clerum.gfs.open(uri) |
gfs.open |
No |
clerum.theme.get() |
theme.read |
No |
clerum.notifications.notify({ title, body?, ref? }) |
notifications.notify |
Yes |
Legacy methods
These two predate the SDK and are kept unchanged.
| Method | What it does |
|---|---|
clerum.requestSessionRefresh() |
Asks the Desktop App to mint a fresh embed session cookie, for when a fetch or SSE stream gets a 401 between scheduled refreshes. Limited to one refresh per 30 seconds per view; a refused call rejects the promise. |
clerum.onOauthCompleted(callback) |
Calls callback({ oauthClientId, provider }) when an OAuth connect flow started from this UI finishes. Returns an unsubscribe function. See the OAuth embed lifecycle. |
Capabilities
Every capability goes through the user's own Desktop session, so Control API authorizes it exactly as it would for the Desktop App's own pages. Consent is an extra gate on top of what the user can already see, never a way around it. Each capability returns a reduced view of the data, listed below.
The Prompt text column is what the user reads in the consent prompt and in
Settings for capabilities that need consent. Your app cannot change it.
gfs.open and theme.read never prompt and never appear as grants.
| Capability | Returns (data) |
Consent | Prompt text |
|---|---|---|---|
identity.read |
{ userId, email, name }. No profile picture URL. |
Yes | See who you are. Your name, email address, and user id. |
org.read |
{ teamId, teamName, role } for the user's current team. |
Yes | See your current team. Its name and your role in it. |
agents.read |
{ agents: [{ id, name, contextRef, provider, mcpServers }] }. mcpServers is a list of server names. contextRef and provider can be null. |
Yes | See the agents you have access to. Their names and which MCP servers they use. |
contexts.read |
{ contexts: [{ id, scope }] }, where scope is 'user' or 'team'. |
Yes | See the contexts you have access to. The names of the contexts available to you. |
mcp.read |
{ servers: [{ name, agents }] }. agents lists the user's agents that can call that server. Server URLs are removed. |
Yes | See the MCP servers you have access to. Their names and which of your agents can call them. |
gfs.list |
{ items: [{ resourceId, gfsUri, name, kind, bytes, version }], nextCursor }. Without resourceId, lists the shared files the user can access; with it, lists that folder's children. |
Yes | See the shared files you have access to. Their names, folders, and sizes. It will not be able to open them. |
gfs.read |
as: 'text': { gfsUri, name, bytes, as, mimeType: 'text/plain', text }. as: 'dataUrl': { gfsUri, name, bytes, as, mimeType, dataUrl }. |
Yes | Open shared files you have access to. It will be able to read the contents of any file you can read. |
gfs.open |
{ opened: boolean }. Opens the file in the Desktop App's own viewer, over the plugin. The plugin never sees the file. |
No | Open a shared file in the Evenfire viewer. Shows you a file you already have access to. The plugin does not see it. |
theme.read |
{ theme: 'light' | 'dark' }. Default 'dark'. |
No | See the app appearance. Whether the desktop app is in light or dark mode. |
notifications.notify |
{ delivered: boolean, reason?: 'suppressed' | 'unsupported' }. |
Yes | Send you notifications. It will be able to get your attention while you work elsewhere. |
Parameters and limits per capability
- No-parameter capabilities (
identity.read,org.read,agents.read,contexts.read,mcp.read,theme.read) returninvalid_requestif you pass any parameter. gfs.listaccepts onlydrive(max 64 characters),resourceId(max 128) andcursor(max 512). Pass the previousnextCursorto get the next page.gfs.readrequiresuri(agfs://link, max 2048 characters) andas('text'or'dataUrl').as: 'text'refuses files over 2 MB (payload_too_large) and files that are not valid UTF-8 (invalid_request).as: 'dataUrl'is for images only. It refuses files over 10 MB and checks the file's actual bytes, not its name: only PNG, JPEG, GIF, WebP and AVIF pass. SVG is refused on purpose; ship vector art in your own bundle.
gfs.openrequires agfs://uri. A failure returnsopened: falsewith no reason, so a missing file and a file the user cannot access look the same. An<a href="gfs://…">link in your UI does the same thing asgfs.openand shares its rate limit.notifications.notifyrequirestitle(max 120 characters);body(max 400) andref(max 256) are optional. Control characters are replaced with spaces. The Desktop App always prefixes the title with your app's title (<app title> — <title>), so a notification cannot pose as Evenfire or as another plugin. It is not shown (delivered: false, reason: 'suppressed') when the user is already looking at your app. When the user clicks it, the Desktop App comes to the front and your app gets anotification.clickedevent carrying yourref.
Events
clerum.sdk.on(callback) delivers these events to every mounted surface of
your plugin:
| Event | Payload | When |
|---|---|---|
theme.changed |
{ type, theme: 'light' | 'dark' } |
The Desktop App's theme changes. |
permission.changed |
{ type, capability, granted: false } |
The user revokes a grant in Settings. Sent immediately, while your app is open. |
session.changed |
{ type, authenticated: boolean } |
The user logs in or out of the Desktop App. |
notification.clicked |
{ type, ref: string | null } |
The user clicks a notification your app sent. |
Consent
The prompt
The consent prompt is drawn by the Desktop App, not by your app. While it is open, the Desktop App hides your app's view, so a plugin cannot fake the prompt or draw over it.
- The heading is
<app title>wants access to your information. Every other word comes from the Desktop App's own capability list. - Rows are sorted most sensitive first (personal data, then workspace data) and start checked. The user unchecks rows to grant only part of a request.
- Allow grants the checked rows. Deny or Escape denies all rows.
- A prompt nobody answers within 120 seconds counts as a denial.
- Only one prompt is shown at a time, across all plugins. The prompt waits until a Desktop window is visible and focused.
Prompt limits
- A plugin can show at most 3 prompts per mount. After that, every ungranted capability is denied until the user reopens the app.
- There are at least 10 seconds between two prompts from the same plugin.
- From the second prompt on, the prompt tells the user how many times this plugin has asked this session.
- A denial lasts for the current mount only: the plugin is not asked again for that capability until the user closes and reopens the app. A mis-click is not a permanent lockout.
- A grant lasts until the user revokes it.
Where grants are stored
Grants are stored on the user's machine, in
<userData>/plugin-consent/ (one JSON file per environment, file mode 0600).
They are scoped to the environment (cluster), the user, the plugin id and the
capability. A grant on one cluster or for one user never applies to another.
Grants do not sync between devices.
If a capability's payload widens in a later Desktop release, the old grant no longer covers it and the user is asked again.
Revoking
Users manage grants in Settings → Plugin permissions:
- The Permissions tab lists each plugin, the permissions it holds and when they were last used. Revoke all removes every grant for a plugin. Expand a plugin to see each permission with the same sentence the prompt showed, and Revoke it on its own.
- The Activity tab lists what plugins requested and the result (Shared,
Granted, Denied, Revoked, Revoked mid-request, Rate limited, Error).
Clear activity log empties it.
theme.readandgfs.opencalls are left out of this view.
Revoking takes effect immediately, even while the plugin is open: the plugin
gets a permission.changed event, cached results for it are dropped, and a call
already in flight returns permission_revoked instead of data.
Activity log
The Desktop App keeps a local activity log in <userData>/plugin-audit/ (one
JSONL file per environment, mode 0600, rotated at 5 MB or 90 days). It records
the shape of what a plugin received (field names, item counts, byte sizes),
never the content.
Errors
| Code | Retryable | Meaning |
|---|---|---|
unsupported_capability |
No | Unknown capability id. |
unsupported_version |
No | The request named a protocol version other than 1. |
invalid_request |
No | Bad or unexpected parameters, a bad capability list, a non-UTF-8 text file, or a non-image dataUrl read. |
unauthenticated |
Yes | The user is not logged in to the Desktop App. |
permission_denied |
Yes | The user has not granted this capability (denied, prompt dismissed, timed out, or prompt budget spent). |
permission_revoked |
Yes | The user revoked the grant while the call was running. |
rate_limited |
Yes | Over a rate limit. The message says how many milliseconds to wait. |
not_found |
No | Not found. Also returned when the user cannot access the item, so the SDK never reveals what exists. |
payload_too_large |
No | The file or result is over the size limit. |
unavailable |
Yes | The Desktop App could not complete the request (for example, an upstream failure). |
internal |
No | The calling view is not a registered plugin surface. |
Rate limits
The Desktop App enforces these limits per plugin, in memory. Budgets refill
continuously rather than resetting every minute, and they reset when the user
closes and reopens the app. A call over a limit returns rate_limited.
| Capability | Per minute | Per hour | Max response size |
|---|---|---|---|
identity.read |
10 | 60 | 4 KB |
org.read |
10 | 60 | 4 KB |
agents.read |
10 | 120 | 256 KB |
contexts.read |
10 | 120 | 64 KB |
mcp.read |
10 | 120 | 128 KB |
gfs.list |
30 | 600 | 512 KB |
gfs.read |
20 | 300 | 20 MB |
gfs.open |
6 | 60 | 1 KB |
theme.read |
60 | 600 | 1 KB |
notifications.notify |
2 | 20 | 1 KB |
| All capabilities, per plugin | 120 | 2400 | — |
A result larger than the capability's maximum returns payload_too_large.
Some results are cached for a short time, so repeated calls return the same
data: identity.read and org.read for 60 seconds, agents.read,
contexts.read and mcp.read for 30 seconds. The cache is cleared on logout,
login and revocation. Cached calls still count against the rate limit.
Security model
What a plugin UI cannot do:
- Claim another identity. The plugin id comes from the view that sent the call, never from the request.
- Answer its own consent prompt. The prompt runs in the Desktop App's trusted window, the plugin's view is hidden while it is open, and the answer channel accepts only the trusted window and a one-time prompt id.
- See more than the user can. Every call uses the user's own session and Control API permissions.
- See infrastructure detail. MCP server URLs and profile picture URLs are removed, and errors never include upstream response bodies.
- Read a file through
gfs.open, or learn why it failed. - Reach other origins. The embed's Content Security Policy is
default-src 'self'; script-src 'self'; connect-src 'self'; img-src 'self' data:(plus related directives). Inline<script>blocks do not run; load your JavaScript from a file served by your UI. Fetches go only to your UI's own origin throughrpc-proxy. A recipe's server-side workload reaches external services throughspec.ui.egress. - Navigate away or open windows. Navigation is pinned to the UI's own path.
http(s)links andwindow.openopen in the user's default browser. Other schemes are dropped, exceptclerum://oauth?clientId=…(starts an OAuth connect) andgfs://…(behaves likegfs.open). - Use device features or download files. Camera, microphone, location, web notifications, USB, serial, HID, Bluetooth and MIDI are all denied; only fullscreen is allowed. Downloads are blocked.
- Use Node.js or Electron APIs. The view runs with
sandbox: true,contextIsolation: trueandnodeIntegration: false.window.clerumis a frozen object.
The SDK is meant to reduce what a plugin can see, not to make an untrusted plugin safe. Only install plugins from publishers you trust.
Example
Serve this as a file (for example app.js) from your UI workload and load it
with <script src="app.js"></script>; the CSP blocks inline scripts.
const clerum = window.clerum
async function start() {
if (!clerum || !clerum.sdk) {
renderWithoutSdk()
return
}
// Follow the Desktop theme. No consent needed.
const theme = await clerum.theme.get()
if (theme.ok) document.documentElement.dataset.theme = theme.data.theme
// Check first, so a returning user sees no prompt.
const wanted = ['identity.read', 'agents.read']
const state = await clerum.sdk.permissions(wanted)
const missing = state.ok ? wanted.filter(id => !state.data.granted[id]) : wanted
if (missing.length > 0) {
await clerum.sdk.requestPermissions(missing) // one prompt for both
}
const me = await clerum.identity.get()
if (me.ok) {
renderGreeting(me.data.name)
} else if (me.error.code === 'permission_denied') {
renderSignedOutView() // a partial grant is normal; keep working
}
const agents = await clerum.agents.list()
if (agents.ok) renderAgents(agents.data.agents)
clerum.sdk.on(event => {
if (event.type === 'theme.changed') {
document.documentElement.dataset.theme = event.theme
}
if (event.type === 'permission.changed' && !event.granted) {
renderSignedOutView()
}
})
}
start()
Plugin UI SDK vs. Plugin Workload SDK
This page covers the browser-side API that a plugin's UI uses inside the
Desktop App. The Plugin Workload SDK is a different, server-side feature: a
recipe's backend workloads declare spec.pluginWorkloadSdk to use
promptBridge (LLM calls) and clientNotifications through Control API, with
its own grants and its own platform rate limits. See
WorkflowRecipe § Plugin Workload SDK
and the Plugin Workload SDK upgrade runbook.
Custom workflow coordinators are built with a third package,
@clerum/workflow-sdk (with
packages/workflow-runtime-core). The rate limits on this page are enforced by
the Desktop App and are separate from the Control API limits in that runbook.