Skip to content

Latest commit

 

History

History
2126 lines (1851 loc) · 114 KB

manifest-reference.md

File metadata and controls

2126 lines (1851 loc) · 114 KB

App Manifest Reference

The app manifest (app.json) declares your app's identity, resources, and requirements.

Required Fields

Field Type Description
name string Unique identifier, kebab-case (e.g. "oncall-watchtower")
version string Semver version (e.g. "1.0.0")
displayName string Human-readable name shown in App Store
description string Short description of what the app does

Recommended Fields

Field Type Description
author string Author name or team
license string License identifier
minKiroCrewVersion string Minimum Gateway version required
tags string[] Discovery tags (e.g. ["oncall", "monitoring"])
jobFamilies string[] Job families this app is relevant to
highlights string[] Concise feature bullets for the detail page
useCases string[] Short, operator-oriented situations where the app is useful
configuration string[] Concise setup or configuration steps shown on the detail page
screenshots string[] Real product screenshots; paths follow the same distribution rules as hero art
screenshotsDark string[] Optional dark-appearance screenshot variants

Admission metadata

Field Type Description
signer string Publisher id looked up in the fleet admission trust keys
signature string Detached signature over the manifest admission payload; generated by publisher tooling

These fields are admission metadata, not a replacement for declaring minimal permissions or setting minKiroCrewVersion.

The signature covers name, version, signer and permissions, plus each of these groups when it is non-empty: notifications, crons, contributes, setup, mcpServers, backend, ui, agents, skills, sops, dependencies, platform and config_keys. An empty group is left out of the signed bytes.

A gateway computes the signed bytes from the groups it knows. A signed manifest that declares a group an older gateway does not sign fails verification there. It fails closed: the install is refused, not downgraded. Set minKiroCrewVersion on a signed app so that refusal names the version floor.

Resources

Field Type Description
agents string[] Paths to agent JSON files (relative to app root)
skills string[] Paths to skill directories
sops string[] Paths to SOP (Standard Operating Procedure) files
mcpServers object MCP server definitions (same format as mcp.json)
config_keys string[] Top-level config.json object keys owned by this app. At most 200 keys may be declared, and each key may contain at most 200 characters. Declarations apply only while the app is installed

How a stdio command is resolved at registration

A stdio entry's command (no url) is not always written verbatim — registration resolves it so the server starts under the interpreter its dependencies were installed against:

  • A bare Python launcher (python, python3, py, or the same with .exe) resolves to the gateway's own interpreter whenever the gateway has provisioned the app's requirements.txt (a pip install --target into data/.kirocrew-deps/; python launchers run through a site.addsitedir shim so .pth files are processed, other commands see the dir on PYTHONPATH; under data/ so app updates keep the last good install) - those wheels are built by that interpreter, so it is the only ABI-consistent choice. Without an active provisioned tree (never provisioned, or provisioning failed), it resolves to the app's own venv interpreter (.venv/bin/python3, or .venv\Scripts\python.exe on Windows) when it exists as a runnable file created by the same Python minor version as the gateway, else again to the gateway's own interpreter - never a PATH lookup. Exception: a server whose args launch a kiro_crew module (-m kiro_crew...) always gets the gateway's interpreter and never the app deps on PYTHONPATH, so an app cannot shadow the gateway's own code.
  • Any other bare name (no path separator, no drive qualifier) is rewritten only when the app's provisioned deps dir or its venv provides that exact binary as a runnable file (a pip console script - invisible to PATH because neither layout is ever activated; the venv is consulted only when no deps dir was provisioned). Note this means an app-provided binary shadows a same-named PATH dependency. node, npx, docker and friends are otherwise left for PATH, as declared.
  • A command carrying a path (absolute or relative) is never rewritten. If it does not point at a runnable file at registration time, a warning naming the app, server, and command is logged — the entry is still written.
  • An app's own .py launcher (a stdio server whose command is a bare python, python3 or py, and whose launch target is a relative path ending in .py, given in args and relative to the app root) is resolved to its absolute path under the app root, so a staged app whose package is not pip-installed can start. A command carrying a path, such as .venv/bin/python, is not covered: its launcher operand is left as written. Only that one operand is touched; -m, -c, and every argument after the script are left as written. The rewrite applies only when the operand resolves (links followed) to an existing file inside the app root; an absolute path, or a relative one that is not such a file, is left as written. A relative path in command itself is still never rewritten.
  • The host CLI name kirocrew is pinned to the running gateway before any of the above applies.

A stdio entry's env values are passed through as declared. A secret://<name> value is not resolved for app servers when kiro-cli spawns them: the server receives the literal reference text. Registration logs a warning naming the app, server and env key when it sees one. How an app may receive a vault secret is undecided (#10641).

Session label for a stdio server (x-kirocrew-session-label)

A stdio server that needs to know which chat session it serves (to tie its own calls to that chat, say) can opt in on its entry:

"mcpServers": {
  "notes": {
    "command": "python3",
    "args": ["server.py"],
    "x-kirocrew-session-label": true
  }
}

Only the literal true opts in. The entry reaches the agent spec as declared, and when a session starts the server receives one extra variable, KIROCREW_SESSION_LABEL, holding that session's key. That is all it receives: no port, no session token, no KIROCREW_SESSION_KEY, and no internal secret. The label is a name, not a credential, and no Kiro Crew identity resolver reads it, so it cannot be presented to the gateway as the session.

The label is set when the server starts and is per session: on the shared kiro-cli runtime it rides the session's own mcpServers element, and on KAS the session's injected agent. It is ABSENT, never stale, in these cases, and the server should treat a missing label as "unknown session":

  • a warm-pool session, which starts its servers before a chat claims it;
  • a server pooled through the MCP gateway (mcp_gateway.stub_servers), which is shared across sessions;
  • an entry the per-session element cannot reproduce exactly, which then starts natively as declared: one with disabledTools, disabled, timeout, cwd, autoApprove, a non-stdio transport, or an env value holding ${NAME} or a secret:// reference;
  • registry mode (agent.mcp_registry_mode), and any other ACP backend.

The server's command, args and env are exactly what it would have started with without the label.

Scheduling

crons — Cron Job Definitions

{
  "crons": [
    {
      "name": "ticket-refresh",
      "every": 300,
      "message": "Check for new high-severity tickets"
    },
    {
      "name": "daily-digest",
      "cron_expr": "0 9 * * 1-5",
      "message": "Generate daily digest",
      "agent": "digest-agent"
    },
    {
      "name": "market-open",
      "cron_expr": "30 9 * * 1-5",
      "message": "Summarise the overnight tape",
      "timezone": "America/New_York",
      "skip_dates": ["2026-12-25"]
    }
  ]
}
Field Type Description
name string Job identifier
every number Interval in seconds (mutually exclusive with cron_expr)
cron_expr string Cron expression (mutually exclusive with every)
message string Prompt sent to the agent on each run
agent string Agent to run (optional, uses default if omitted)
agent_sequence string[] Ordered agents to run
command string Shell command executed without a model call; mutually exclusive with script. A present non-string value is rejected rather than treated as absent
script string Synchronous Python callable (file.py:function) executed without a model call; mutually exclusive with command. A present non-string value is rejected rather than treated as absent. The path resolves against the app's own bundle, must stay inside it, must name a .py file, and is stored as an absolute path; re-enable the app after its bundle moves
env object String environment variables passed to the job
persistent_session boolean Default true; retain one agent session across runs
silent boolean Default false; suppress automatic result delivery
folder string Schedule-folder name. Installing, enabling or updating the app in a running gateway creates a missing folder; a name several folders share, registration during gateway startup, or a CLI enable leaves the job ungrouped
timezone string IANA zone name the schedule and skip_dates are evaluated in, e.g. America/New_York. Optional, but an empty value falls back to the gateway config's timezone and then to UTC — so "cron_expr": "0 6 * * *" without it fires at 06:00 UTC, the wrong calendar day for most users. An unknown zone is rejected at manifest validation. A per-user zone is not manifest data: pass timezone= to ctx.cron.add_job instead
skip_dates string[] Calendar dates the job must not fire on, evaluated in timezone. Must be zero-padded YYYY-MM-DD — 2026-1-1 parses but never matches the padded fire-time rendering, so it is rejected at manifest validation rather than silently skipping nothing
timeout number Seconds a command or script subprocess may run. 0 or omitted uses the scheduler default: 30s for a script, 300s for a command
timeout_secs number Seconds one run may take in total, within 1..86400. 0 or omitted uses the scheduler default. On a command or script cron it must cover timeout (or that default) plus 5s of cleanup, so a script that runs 40s needs both, e.g. "timeout": 60, "timeout_secs": 65. A value the cron SDK would refuse is rejected at manifest validation
strict_schedule boolean Default false. When true the job fires exactly on its schedule instead of after the scheduler's random start delay, which spreads jobs out and on a daily job can reach 59 minutes. Use it for a time the user chose on purpose, such as a report wanted ready at 06:50. Must be a JSON boolean; any other type is rejected at manifest validation
enabled boolean Default true. Must be a JSON boolean — any other type is rejected at manifest validation. When false the cron is registered paused (visible in the Schedule view, resumable) instead of firing on install/enable — for jobs that need user configuration first

A manifest that declares any crons must also declare "cron": true under permissions: a schedule runs unattended, so the permissions an operator reviews before installing name it. Install, update and self-registration refuse a manifest without it, with an error that names the fix. An app installed before it declared the grant keeps loading and firing its crons; it meets the rule on its next update.

Changing a cron after install. Each registered job remembers, field by field, the manifest entry it was built from. When the app's crons are registered again -- an app update, a gateway start, an enable -- each field in the table above whose manifest value changed is re-applied to the job; enabled is the exception, being the initial pause state only. A field the author did not change is left exactly as it is, including any edit the user made to it on the Schedule page, and so is a job whose entry did not change at all. The precedence is manifest over hand edit for a field the author changed, hand edit over manifest for a field the author did not, and the user's pause state over the manifest always: a paused job gets the new values and stays paused. Settings the manifest does not own -- a delivery channel, a model, chat visibility, a secret grant -- are never touched. A change to command, script, agent_sequence or env is the exception: the scheduler accepts those fields at creation only, so the change is logged (and audited as app_cron_resync_pending_reenable) on every registration until the job is recreated, which is when it reaches the job: the app is disabled and enabled again, or a Sync of an app with backend hooks reloads its code; the entry's other changed fields still land at once. A message cleared to empty is reported the same way, because the scheduler keeps the stored prompt on an empty value. A job registered by a build that did not yet record its entry is brought up to the manifest once, on the next registration: nothing recorded which entry it came from, so the manifest is applied even if the author changed nothing, and an edit the user made to one of its manifest-owned fields is replaced. The gateway log names each replaced field with its old and new value (a WARNING line ending in "job predates the manifest stamp") so the user can put the edit back.

Caveat: disabling an app deletes its registered cron jobs when a cron service is reachable, and re-enabling the app re-registers them from the manifest. A cron shipped with "enabled": false that a user later resumed will therefore be reset back to the paused state after an app disable → re-enable cycle and must be resumed again. A job the disable could not remove stays in the store but does not run while the app is disabled: each fire is skipped and the run is marked as an error. It runs again once the app is re-enabled.

Frontend UI

ui — Dashboard Integration

{
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [
      {
        "route": "/apps/my-app",
        "label": "My App",
        "icon": "Shield",
        "entryPoint": "dist/page.mjs",
        "mountFunction": "mount"
      }
    ],
    "sidebar": {
      "section": "Apps",
      "order": 10
    }
  }
}
Field Type Default Description
ui.entry string Path to ESM bundle (relative to ui/)
ui.pages[].route string URL path for the page
ui.pages[].label string Sidebar label
ui.pages[].icon string Lucide icon name (e.g. "Shield", "Package"). Built-in apps only: an installed app's sidebar row shows the generic icon for it, so ship an image instead (iconPath, or ui.pages[].iconUrl)
ui.pages[].iconUrl string Custom active icon image path (relative to ui/)
ui.pages[].iconInactiveUrl string Optional sidebar icon for when the app is not selected (relative to ui/). Read from the first page. The sidebar row shows this file while another page is open, and the app's normal icon when its own page is open or the row is hovered. Use it for a greyed-out variant, the way built-in icons go grey. If the file fails to load, the row keeps the normal icon
ui.pages[].entryPoint string Per-page ESM bundle path, relative to ui/ (overrides ui.entry)
ui.pages[].mountFunction string "mount" Exported function name in the ESM bundle
ui.sidebar.section string "Apps" Sidebar section name
ui.sidebar.order number 10 Sort order within section
ui.overlays[].id string Overlay id; must match a bundled overlay component (see below)
ui.overlays[].replaces string Host overlay slot this app takes over while enabled
ui.loading.layout string "page" Placeholder shape shown while the bundle loads: "page", "rail", "centered" or "split" (see below)
contributes.sessionControls[].id string Control id, kebab-case; addressed as <appName>:<id>
contributes.sessionControls[].entryPoint string ESM bundle path for the control (relative to ui/)
contributes.sessionControls[].label string Accessible name, and the chip's tooltip
contributes.sessionControls[].icon string Icon name. Only Shield, Bot, Search, Tag, Users, Zap, Star, Package, Cat, AudioLines and Mic are rendered; any other name falls back to Package. Use AudioLines for a control that starts a voice conversation and Mic only for voice input: the composer's own dictation button already draws Mic, so a conversation chip with that glyph reads as a second dictation button
contributes.sessionControls[].statusPath string Optional backend route reporting per-session chip state (see below)

ui.loading — Loading Placeholder Shape

While your bundle downloads, the dashboard shows a placeholder. Nothing appears for the first 300 ms, so a fast load (the usual case on a local gateway) shows no placeholder at all. After that, the placeholder takes the shape you declare, so your page doesn't jump when it mounts:

{
  "ui": {
    "entry": "dist/index.mjs",
    "loading": { "layout": "rail" }
  }
}
layout Shape
"page" Title bar, subtitle bar and content rows. The default
"rail" A 232px left column of list rows beside the main content
"centered" One narrow card in the middle of the page, e.g. a composer or a sign-in
"split" Two panes side by side, e.g. a list and a detail view

The shapes are drawn by the dashboard from its own skeleton pieces. You pick a name; you can't supply markup or styles. The match is exact: a missing or null loading, a non-object, a non-string layout, or an unknown name (including a different case, like "Rail") all fall back to "page". An invalid value is not an install error; it is dropped.

ui.overlays — Replacing a Host Overlay Surface

An overlay is a surface that floats above whatever the user is looking at and is opened by a gesture the host owns, so unlike ui.pages it has no route and no sidebar placement. Declaring one lets an enabled app take over a host surface:

{
  "ui": {
    "overlays": [
      { "id": "command-bar", "replaces": "quick-search" }
    ]
  }
}

replaces names a host slot. quick-search is the only slot the dashboard currently offers -- it is the Cmd+K / Ctrl+K surface -- and an unknown slot name is reported and ignored rather than silently dropping the overlay.

Host-internal until App Kit adopts it. Both fields are validated by the backend for any manifest, but only an app whose origin is builtin can actually claim a slot: an overlay id must name a component compiled into the dashboard bundle, and there is no ESM entryPoint for overlays the way ui.pages has one. An installed app declaring ui.overlays is refused at install, and a self-registered one is refused when slots are resolved -- builtin provenance is assigned only by the builtin registration Kiro Crew runs at startup and cannot be self-reported. Treat this as the mechanism builtin apps use to replace a host surface, not yet as a third-party extension point.

A builtin declaring ui.overlays must NOT also declare ui.entry: builtin registration re-derives origin on every startup and downgrades an app that ships a UI bundle to local, which would then be refused its own slot. A test enforces this so the combination fails the build rather than silently reverting the surface.

At most one enabled app owns a slot. When two enabled apps declare the same replaces, the first by app name wins and the collision is reported -- the winner does not depend on which app was enabled or installed more recently.

l10n — Listing Copy per Locale

Optional. Your app's display name, description, page label and highlights in other languages. The dashboard shows them in place of the English fields for a reader whose language matches: first the exact locale, then its base language, then the English field.

{
  "l10n": {
    "de": {
      "displayName": "Einkaufsberater",
      "description": "Merkt sich, was dir wichtig ist, und hilft beim Vergleichen.",
      "pageLabel": "Einkauf",
      "highlights": ["Merkt sich Größen und Vorlieben", "Vergleicht Angebote"]
    },
    "zh-CN": { "displayName": "购物顾问" }
  }
}
Rule Limit
Locale key ^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$ (de, pt-BR, zh-CN), at most 32 locales
displayName string, at most 120 characters
description string, at most 1000 characters
pageLabel string, at most 60 characters
highlights array of at most 12 strings, each at most 300 characters

Every field is optional. A locale with an unknown key or a value over its limit is dropped and the install logs a warning; the rest of the block, and the install, are unaffected. The block is listing content, not a signed field, so it is not part of the admission signature. A built-in's own dashboard catalog keys take precedence over it.

The published store listing does not carry l10n yet, so a store row you have not installed shows the English fields.

Declarative contributions

contributes.commands — Adding Rows to the Command Bar

Adds command rows to the host's Command Bar. This is the lightest thing an app can be: a command-contributing app needs no page, no frontend bundle, no backend and no process — a manifest, plus whatever skill its prompt names.

{
  "contributes": {
    "commands": [
      {
        "id": "approve-all",
        "title": "Approve all PRs",
        "subtitle": "Approve every pull request behind a link",
        "icon": "Check",
        "keywords": ["pr", "lgtm"],
        "argument": {
          "placeholder": "Paste a GitHub link…",
          "hint": "A PR search, a label, or a single pull request.",
          "kind": "url",
          "hosts": ["github.com"],
          "patternError": "Not a github.com link."
        },
        "prompt": "Load the $my-skill skill and approve every PR behind {argument}",
        "autoSend": true
      }
    ]
  }
}
Field Required Notes
id yes lowercase alphanumeric + dashes; unique within the app
title yes row label, up to 120 characters
prompt yes the action: a new session is seeded with this text, up to 4000 characters
subtitle no defaults to the app's display name
icon no a name from the host's glyph set; an unknown name falls back
keywords no hidden match aliases
argument no the ONE value the command collects before it runs; must be an object
autoSend no send the seeded prompt instead of leaving it in the composer
agent no the agent the new session runs as; must be the JSON name one of THIS app's own agents declares, matching [A-Za-z0-9._-]{1,120}. Omitted means the dashboard default

Every entry of commands must be an object, and every length above is counted in UTF-16 code units -- what the launcher itself counts. Both matter for the same reason: the host validates your manifest twice, once on install and once when it renders, and anything the two would measure differently is a command that installs clean and then does not appear. So a title of 100 emoji is 200 units, not 100, and a single non-object entry is refused rather than quietly skipped past.

Inside argument:

Field Required Notes
kind no url or text; defaults to text. An unknown kind is refused
hosts no url only: allowed hostnames, up to 20. Empty means any host
placeholder no field placeholder
hint no one line under the field
patternError no shown when the value is not accepted

contributes sits beside ui, not inside it: ui declares surfaces the app owns, while a contribution is a row inside a surface the host owns and renders.

A contribution is data, never code. There is no way to ship a function or an icon URL: the launcher would be running app-authored JavaScript inside the host's surface on every keystroke, and the root page promises to issue no network request. Ask for a new glyph name by pull request.

The host owns the matcher; a manifest names one rather than supplying it. The collected value is spliced into an instruction handed to an agent with tools, so it has to be checked before the prompt is built — but kind selects one of a fixed set the host implements, and there is no way to ship a regex of your own. An earlier revision of this contract accepted argument.pattern; a pattern from a manifest runs against the field on every keystroke on the thread that draws the launcher, and shapes like ^(a+)+$ or ^(a|aa)+$ are a few characters long and exponential, so an argument that still carries pattern is now REFUSED rather than migrated — leaving it to fall back on text would accept any non-empty string with autoSend still on. An unknown kind is refused for the same reason.

kind: "url" parses the value with the runtime's own URL parser and then applies hosts. The allowlist is exact unless an entry starts with a dot: github.com does not admit github.com.evil.test, while .github.com admits gist.github.com. Only http and https are accepted. kind: "text" takes any non-empty value.

This is less precise than a regex, deliberately: a pattern could demand /pull/<n>, while url + hosts admits any URL on the host and leaves what the link DENOTES to the agent — or to your skill, which is the better place for your own product's URL taxonomy.

Declaring an argument the prompt never interpolates is an error — the reader would be asked for a value the command then ignores. A command whose prompt needs no value simply omits argument; activating it is the whole action.

agent is contained to your own agents. The prompt is app-authored, so a command may not name a host agent -- one that may carry broader tool grants or auto-approvals than the default would otherwise run your text with that reach. Install refuses an agent that is not one of the agents this manifest ships, and refuses a value outside the pattern above rather than letting the launcher drop it to the default later. The app listing re-checks every command's agent against the agent files on disk (a self-managed app's app.json never passes install validation), drops one that is not yours, and the session selects it as a template, so a host crew member sharing the name cannot take it over. The session also remembers that it runs your app's agent, and each turn is refused (with an error in the chat) if that name would resolve to any other spec, such as an agent in the session's project .kiro/agents that declares the name or is a file of that name. A session with no project is checked against every folder it can start in instead.

What the reader sees with autoSend. The host shows the resolved prompt — the template with the reader's value already spliced in — in the argument field before the send, so the instruction is visible at the moment it fires. Write prompts on the assumption they will be read.

autoSend requires an argument. That preview is what makes the send informed and it lives in the argument step, so a command that collects nothing never reaches it and the combination is refused rather than silently downgraded. Such a command still works: its prompt lands in the composer and one keystroke sends it. autoSend is also honoured only for the JSON boolean true, never for the string "true".

A malformed command is skipped with a console warning and the app's other commands still load. Commands from a disabled app do not appear at all.

If your app is SIGNED, set minKiroCrewVersion. Contributions are covered by the admission signature -- a contributed prompt goes to an agent with tools and autoSend fires it, so leaving it unsigned would make your rows the one part of a signed app an attacker could rewrite with the signature still verifying. A gateway that does not sign contributes computes the signed bytes without it, so a signed manifest declaring contributes fails CLOSED there (see Admission metadata). The error will not obviously point here, so declare the floor and the install refuses for a legible reason instead. Unsigned apps are unaffected, as are signed apps that contribute nothing: the key is only added to the payload when non-empty.

contributes.sessionControls — A Per-Chat Control in the Composer

A session control is a compact chip the dashboard renders in the composer bar, beside the agent, model and project chips. Opening it mounts the app's own ESM module and hands it the identity of the chat the user is currently in -- which is the reason the slot exists, because nothing else in the app surface reports that. ui.pages is routed and session-blind, so a per-chat setting placed there makes the user leave the conversation to configure it.

{
  "contributes": {
    "sessionControls": [
      {
        "id": "env-picker",
        "entryPoint": "dist/session-control.mjs",
        "label": "Environment",
        "icon": "Tag",
        "statusPath": "session-status"
      }
    ]
  }
}

Unlike ui.overlays, this is a third-party extension point: an installed app may declare it, and the control is loaded through the same lazy import() and import map ui.pages uses, so React stays a single instance.

What the control is handed. The module's default export is rendered as <Control session={…} onClose={…} />, where session is:

Prop Type Meaning
session.sessionKey string Session key, e.g. dashboard:chat-2-1787502679. Empty before a slot exists
session.folderId string? Folder the chat is filed in, '' at top level. A dashboard grouping with its own id -- not a directory, so key per-folder state on this and not on cwd
session.folderName string? Folder's display name, to name it back to the user
session.cwd string Working directory recorded for the session, when known
onClose function Dismiss the control, e.g. after committing a change

The control is remounted when the session changes, so per-chat state cannot leak across a switch, and a control that throws renders an inline notice instead of disturbing the chat.

Two caps, and the second one drops. The backend allows at most 2 controls per app. The dashboard renders at most 2 across all apps, and controls past that are dropped rather than moved into an overflow menu -- the bar shares one row with the message input. With three or more contributing apps, a declared control can therefore be absent.

statusPath — reporting state before the chip is opened. Without it a control can only report anything once its module loads on first click, so a configured setting looks unset. When declared, the dashboard GETs the route under the app's own route base, with session_key always and folder_id / folder_name when the chat is in a folder, and reads:

{ "state": "ok", "tooltip": "Bound to production", "detail": "production" }

state is ok, warn or none; the chip tints for the first two and the tooltip is length-bounded. The optional detail is shown on the chip after the manifest label, as <label> — <detail>, so the per-session value is visible without hovering while the label still identifies the control. Make detail the bare name the control is bound to (production, not Bound to production) and let tooltip state the relationship. It is cut to 40 characters after control, format, bidi, zero-width and line-separator characters are removed; a missing or non-string detail shows the label alone. A detail is shown even when state is none. The path is charset-bounded at install and re-checked in the dashboard, and one that would leave the app's own route prefix is refused before any request rather than sanitized -- so a control with an invalid statusPath is simply never polled. Polling fails closed: an app that is down is not retried, and an unrecognized payload is treated as none.

When the status is re-asked. Once when the chat opens, again when the user closes the control's popover, and again each time a turn in that chat finishes. A change the app makes between turns (a cron job, another session) shows on the next of those moments, not before: there is no polling interval.

The route base follows how the app serves its backend, and the dashboard derives it -- an app declaring backend.entryPoint runs its own process and is reverse-proxied at /apps/<app>/api/, while one declaring only backend.hooks.routes is registered in-gateway under /api/apps/<app>/. Both prefixes are built by the host from the app name, so statusPath stays the only app-authored part of the URL. Declaring the wrong one is not possible: an app does not choose.

contributes.fileMenuItems — Rows in File / Tree / Folder Menus

Declares rows an app adds to the file-editor overflow (⋮) menu, the workspace tree context menu, and the folder panel. Like contributes.commands, it is declarative and host-rendered: core reads the declaration, draws the rows, and POSTs to the app's own endpoint on activation — it never imports app code and holds no live callback, which is what makes the rows reachable by an app installed at runtime.

{
  "contributes": {
    "fileMenuItems": [
      {
        "id": "send-to-store",
        "label": "Send to store",
        "icon": "Package",
        "endpoint": "/api/apps/doc-store/send",
        "surfaces": ["file-overflow", "tree-context", "folder-row"],
        "when": { "extensions": ["md", "txt"], "kinds": ["file"] }
      }
    ]
  }
}
Field Type Purpose
id string Stable, app-owned row id (lowercase kebab slug, [a-z0-9][a-z0-9-]*), unique within the app
label string Row label, max 120 characters (an app-owned literal — not a core i18n key)
icon string Host glyph name: one of Shield, Bot, Search, Tag, Users, Zap, Star, Package, Cat, AudioLines, Mic. Any other name falls back to Package
endpoint string App route core POSTs to; must sit under /api/apps/<your-app>/ (in-gateway, for a backend.hooks.routes app) or /apps/<your-app>/api/ (the reverse proxy, for a backend.entryPoint app). Core refuses to follow a redirect out of it, so the route must answer directly rather than forward
surfaces string[] Any of file-overflow, tree-context, folder-row
when.extensions string[] Match these file extensions (lowercase, no dot; empty = any)
when.kinds string[] Match file and/or dir (empty = any)

At most 10 rows per app.

On activation core POSTs { item_id, surface, path, kind?, root? } to endpoint. A successful JSON response may include a nonempty string message and an optional url. Core shows the message as plain text in a local host toast with a clickable HTTP(S) link. Unsafe URLs, including script/data schemes and credential-bearing URLs, are not linked. An absent, empty, or non-string message produces no toast. The toast holds only the latest result: a second result that arrives before the first hides replaces it. HTTP failures keep the existing host error notice; a toast neither grants access nor changes the endpoint's approval flow.

The file's PATH is sent, never its CONTENT. A contributed row needs no permission to exist, so shipping file bytes with every activation would hand any app that declares a row the contents of whatever file the reader clicked, with no install-time declaration and no consent step. An app that needs the bytes reads them through a route its own permissions cover.

when is evaluated by core, so an app cannot run code in the host to decide visibility. An endpoint outside the app's own namespace (or one using .. traversal) is refused at install — the same allowlist publishProvider uses. For a signed app the rows are covered by the signature, because endpoint is where core sends the reader's chosen path. A stock build with no app declaring these renders nothing.

Store artwork

App Icon

iconPath is the App Store's card and row icon, and it is top-level — not under ui. ui.pages[].icon and ui.pages[].iconUrl above are the sidebar glyph for an app that is already installed, a different surface; neither one supplies a store icon, and an app that declares only those publishes no icon at all.

{
  "iconPath": "assets/icon.png",
  "iconPathDark": "assets/icon-dark.png"
}

iconPathDark is optional; when absent, the opaque iconPath asset is reused.

kirocrew app init scaffolds assets/icon.png and this field, so a new app starts with a working icon rather than a placeholder card. Replace the generated placeholder with real artwork before publishing.

For the artwork requirements — path form, dimensions, why the icon must be opaque, and how the dark variant relates — see Publishing an app, which owns that spec for every art field.

Hero Images

Top-level manifest fields that supply the artwork rendered on App Store browse and detail cards. The path form depends on how the app is distributed:

  • Builtin apps use an absolute served URL under /apps/{name}/ui/ (the builtin registry serves the app's bundled ui/ directory there):

    {
      "heroImage": "/apps/my-app/ui/hero-light.svg",
      "heroImageDark": "/apps/my-app/ui/hero-dark.svg",
      "heroImageDetail": "/apps/my-app/ui/hero-detail-light.svg",
      "heroImageDetailDark": "/apps/my-app/ui/hero-detail-dark.svg"
    }
  • Federated / registry apps use a repo-relative path (e.g. ui/hero-light.svg); _merge_manifest (apps/registry_pipeline/manifests.py) rewrites it to a blob-proxy URL (/api/apps/blob?repo=<repo>&path=<path>) so the artwork resolves without the app being locally installed. The path is relative to the directory app.json lives in: for a registry entry that declares a subdirectory, the rewrite prefixes it (apps/<name>/ui/hero-light.svg), so the manifest is written the same way in a monorepo as at the repo root:

    {
      "heroImage": "ui/hero-light.svg",
      "heroImageDark": "ui/hero-dark.svg",
      "heroImageDetail": "ui/hero-detail-light.svg",
      "heroImageDetailDark": "ui/hero-detail-dark.svg"
    }
Field Type Description
heroImage string Hero image shown on the App Store card (light theme)
heroImageDark string Hero image variant used in dark theme
heroImageDetail string Wide banner preferred by the detail page (light theme)
heroImageDetailDark string Wide detail banner used in dark theme

Hero images are illustrative marketing art. screenshots are separate and must show the real product UI; the detail page renders both when both are declared.

Chat side-panel contribution

contributes.panelTabs — Chat side-panel tabs

A body-owning tab in the chat side panel, declared like a page and mounted through the same in-process ESM app host ui.pages use (never an iframe). The frontend keys the tab on app:<app_name>:<id> and persists it as metadata, so it survives a reload and re-mounts its entry.

Field Type Default Description
contributes.panelTabs[].id string Stable tab id, unique within the app; storage-safe slug ([a-z][a-z0-9_-]{0,63})
contributes.panelTabs[].title string Tab strip label
contributes.panelTabs[].menuLabel string Row label in the side-panel "+" menu and the empty-panel launcher
contributes.panelTabs[].menuDescription string Optional one-line description shown under the launcher card
contributes.panelTabs[].icon string Icon name from the app icon set below (e.g. "BookOpen")
contributes.panelTabs[].entry string ESM bundle path mounted as the tab body, relative to the app's ui/ directory

The entry base is the app's ui/ directory, not the app root: the reader mounts it from the one static route apps are served through, /apps/<name>/ui/<entry>, so "panel.mjs" is the file at <app root>/ui/panel.mjs and a leading "ui/" would resolve to ui/ui/. Same base as ui.entry.

An app may declare at most 8 panel tabs; the cap is enforced by the manifest and by the reader, so tabs past it are dropped with a warning rather than rendered. Labels are the app's own literals (the core has no i18n catalog key for a tab it does not know), so they render as declared. The tab body is a normal app UI bundle: it runs in-process behind the same permission-scoped API provider as an app page.

icon accepts one of the following names. The set is fixed rather than the whole Lucide catalog, because resolving an arbitrary name would mean bundling every icon; an unrecognised or absent name renders a generic panel glyph.

Activity, AudioLines, Bell, BookOpen, Bot, Boxes, Bug, Cloud, Code, Database, FileText, Files, Folder, FolderTree, GitBranch, Globe, Inbox, Layers, Link, ListTodo, Mic, MessageSquare, Package, PanelRight, Pin, Search, Settings, Shield, Sparkles, Star, Table, Tag, Terminal, Users, Wrench, Zap

Backend

contributes.linkPreviews — Hover Cards for Links

A link preview shows the app's own card when the user hovers a link in a chat message (links elsewhere in the dashboard never reach an app). The host owns detection (which links, the 300 ms hover delay, leave, Escape, scroll and blur); the app owns the card, which runs in a sandboxed frame. No app code runs until a link on one of the provider's hosts is hovered.

{
  "contributes": {
    "linkPreviews": [
      {
        "id": "cards",
        "entry": "dist/link-preview.mjs",
        "hosts": ["tickets.example.com", ".example.dev"]
      }
    ]
  }
}
Field Type Description
id string Storage-safe slug, unique within the app
entry string ESM module, relative to ui/ (same base as ui.entry)
hosts string[] 1-64 hostnames; a leading dot means the domain and every subdomain. Only https: links match. Stored lowercased, in IDNA (punycode) form and without a trailing dot. A public suffix (co.uk, .github.io) or a bare TLD (com) is refused
textPatterns object[] Optional. Plain text in chat messages that also opens a card; see below
fullUrl boolean Optional. show gets the URL without its query and fragment unless this is true and the owner approved it

Approval. The hosts, the text patterns (id, flags and source) and fullUrl are part of what the owner approves for the app, like permissions.api. An update that adds a host, changes a pattern or turns fullUrl on waits on the app's page until the owner approves it, and until then the app previews only what was approved before. An update that only removes entries needs nothing. When no host and no pattern is approved, the provider is off: no frame is made, and a live frame's capability stops renewing and its fetches are refused.

At most one provider per app; a link goes to the first enabled app whose hosts claim it.

Where the module runs. Never in the dashboard's document. On the first hover the dashboard creates an iframe for the provider that is sandbox="allow-scripts" with no allow-same-origin, and loads a frame document the gateway serves at /app-frame/<app>/linkPreviews/<id>/… with its own Content-Security-Policy: sandbox allow-scripts. The frame's origin is opaque: it cannot read the dashboard's DOM, its cookies, its storage or its token. The iframe is credentialless, the frame's CSP starts from default-src 'none' (scripts and network on the gateway only, images from any https: host, no workers, frames, objects, forms or <base>), and it is sent with Referrer-Policy: no-referrer. A frame that navigates itself away is removed. The frame imports entry and calls activate(ctx) once. The dashboard sends it only the hovered URL or text, the anchor's rect, the theme and the modifier keys, over postMessage, and it positions and sizes the frame itself.

export function activate(ctx: {
  appName: string
  theme(): 'dark' | 'light'
  /** fetch() to this app's own backend routes; `path` is relative. */
  fetch(path: string, init?: RequestInit): Promise<Response>
  /** Which `textPatterns` ids this app's settings turn off now. */
  setTextPatternsOff(ids: string[]): void
  // Overlay mode: the frame covers the viewport and is clipped to these rects.
  setRegions(rects: { left: number; top: number; width: number; height: number }[]): void
}): {
  // A link: `url`. A `textPatterns` match: `text`. `rect` is where it is on screen.
  show(link: {
    url?: string; text?: string; theme: 'dark' | 'light'
    rect: { left: number; top: number; width: number; height: number }
    modifiers?: { alt: boolean; shift: boolean; ctrl: boolean; meta: boolean }
    // Card mode: the controls for THIS show's card, placed next to its link.
    card: {
      open(): void
      close(): void
      resize(size: { width: number; height: number }): void
      pin(pinned: boolean): void          // a pinned card stays on leave and chat scroll
      dragBy(dx: number, dy: number): void
      dock(edge: 'left' | 'right' | null): void
    }
  }): void
  leave(): void              // the pointer left the link; the card may hold itself open
  hide(reason: string): void // 'scroll' | 'escape' | 'blur' | 'other-provider' | 'disabled'
  theme?(theme: 'dark' | 'light'): void
  dispose?(): void           // the app was disabled
}

Two ways to draw:

  • Card mode (the default). The module renders its card into the frame's document.body, reports the size with link.card.resize, and shows it with link.card.open. The dashboard places the frame below the link (above when there is no room) and keeps it on screen. card.pin(true) keeps the card when the pointer leaves or the chat scrolls; the next hover then gets a fresh frame, and at most 8 cards stay pinned. card.dragBy moves it (use screenX/screenY deltas: the frame moves under the pointer) and card.dock sticks it to an edge. A scroll inside the card stays in the frame and never closes it, and a scroll elsewhere closes it only when it moved the hovered link.
  • Overlay mode, for a provider that keeps windows of its own (pinned cards, a dock, a settings dialog). Its first ctx.setRegions makes the frame cover the viewport, clipped to the rects it reports; outside them the page stays clickable. The frame's viewport is then the dashboard's, so rect is exactly where the link is. Card-mode calls are ignored, and hide is only a notice: the module decides what closes.

Every show starts a new invocation, and its link.card is bound to it. Keep the card of the show you are answering: a call on an earlier show's card, for example from a slow fetch that finished after the user moved to another link, is dropped. A message over 8 KB, or past a burst of 120 messages refilled at 60 a second, is dropped unread.

Links in a card open through the dashboard's link bridge, only right after a click in the card. A plain key pressed in the dashboard while a card shows is passed to the frame as a keydown, so a card's own shortcuts work; never while the dashboard is taking text (a field, or an editor inside a shadow root), and never with Ctrl, Alt or Meta.

ctx.fetch reaches the app's own backend routes and nothing else: the routes it registers through backend.routes, or its process backend through the same signed proxy as /apps/<app>/api/. Core routes under /api/apps/<app>/ are not reachable. The request carries a capability the dashboard mints for that one frame (X-KiroCrew-Capability), short-lived and renewed while the frame lives; no cookie is sent and no other route accepts it. Only GET, POST, PUT, PATCH and DELETE are forwarded; any other method gets 405.

If the app list cannot be read, a hover on a chat link shows the same notice and the list is asked for again. If the frame does not report ready within 10 seconds, or the module fails to import, or activate throws, the host logs the error, shows a short "couldn't load this preview" notice under the hovered element, and tries again on a hover at least 30 seconds later. When the app is disabled the host sends hide('disabled') and dispose, then removes the frame.

Plain text (textPatterns). Each entry names text that is not a link but should open the app's card:

"textPatterns": [
  { "id": "ticket", "pattern": "(?<![\\w-])(TK-\\d{4,})(?![\\w-])", "flags": "g" },
  { "id": "team", "pattern": "(?<![\\w.-])(team\\.[a-z0-9]+)", "flags": "gi", "defaultOff": true }
]
Field Description
pattern JavaScript regex source, at most 200 characters; at most 16 entries
flags Optional. A subset of giu; g is implied
id Optional slug the module names in ctx.setTextPatternsOff
defaultOff Optional. Not drawn until the module reports it on
  • In chat messages only, the host wraps each match in <span class="link-preview-text" data-link-preview-text>. It is never a link, and never drawn inside code, inline code, math, raw HTML or an existing link. A token an edition's autolink rule already linked stays that link.
  • Hovering the span calls show({ text, rect }) on the app whose pattern matches the span's whole text. The span carries no owner: the host re-derives it from the text, so a span written in raw message HTML reaches nothing a pattern would not.
  • ctx.setTextPatternsOff(ids) reports which ids the app's own settings turn off. The host remembers it across reloads, so the first paint after a reload already follows the app's settings although the module only loads on the first hover.
  • A pattern must compile with its flags and must not match the empty string. It is never run on the dashboard's thread, not even for that check: matching and the empty-string test happen in a Web Worker, one batch per render, with a hard budget of 250 ms per pattern, restarted as each pattern starts, so an overrun is charged to the pattern that used up its own time. A pattern that matches the empty string is turned off for the session. A pattern that overruns is stopped (the worker is terminated), turned off for the rest of the session, and logged once; the rest of the batch, and text already drawn, is matched again without it, so a span it owned can move to the next app whose pattern takes it. A text node longer than 2,000 characters is not scanned. Text renders plain until the worker answers, then gains its spans. A span belongs to the first app (in app-list order) whose pattern matches its whole text, the same in every message. At most 20,000 distinct text nodes are scanned per page load; later ones stay plain. If the worker does not start within 5 seconds, plain-text previews are off for that page load. textPatterns is signed.

contributes.messageActions — A Button on One Chat Message

A message action is a row in a chat message's More menu. When the user clicks it, the app gets that one message's text, in a popover next to the message. Nothing else: no other message, no session key, title, folder, agent, model or project, no attachments, tool calls or their output, no message id or position, and no DOM. No app code runs until the row is clicked. It runs in the same sandboxed frame as a link-preview card.

{
  "contributes": {
    "messageActions": [
      {
        "id": "save",
        "title": "Save to notes",
        "entry": "dist/frame.mjs",
        "roles": ["assistant"],
        "format": "plain",
        "maxChars": 32000,
        "popover": { "width": 360, "maxHeight": 480 }
      }
    ]
  }
}
Field Type Description
id string Storage-safe slug, unique within the app
title string The menu row's label, 1 to 40 UTF-16 units. The row also names the app
entry string ESM module, relative to ui/ (same base as ui.entry)
roles string[] Optional. Which messages the row is on: assistant (replies, the default), user (the user's own messages), or both
format string Optional. plain (default): the message's own text as the chat renders it, minus what the renderer hides, read at the click: a link gives its label, not its address; an image or a drawn diagram gives nothing; a formula gives its TeX; a code block gives its code. Styling the message's author applied counts as content. markdown: the markdown source
maxChars integer Optional. 1 to 32,000 (default). Longer text is cut, and truncated says so
popover object Optional. width 200 to 480 (default 360) and maxHeight 120 to 600 (default 480), in CSS px

At most two actions per app. A field with the wrong JSON type, or an unknown field, is refused at install, never coerced. Every entry is signed.

Approval. Which roles an action is on and whether it gets markdown are part of what the owner approves for the app, stored per action as <id>:role:assistant, <id>:role:user and <id>:format:markdown in the messageActions family of the approved-grants file. Installing approves what is declared. An update that adds the user role, switches to markdown or adds an action waits on the app's page under Approve new permissions; until then the action works at its approved reach (an action whose markdown waits gets plain text). An update that only narrows needs nothing. An action with no approved role is not offered, its frame is not served, and an open frame's fetches are refused. User messages are a grant of their own because a user's message can hold what they pasted; an assistant reply can hold what the agent read, so neither role is free.

Where it shows. In the More menu of each finished message of an approved role, after the host's own rows, ordered by app name. Never as a row button: the message footer keeps its two-control limit whatever apps are installed. Not on a streaming reply. On a user message, only where the row has a More menu (the chat surfaces that offer Quote).

Where the module runs. In an app frame (see linkPreviews above for the sandbox, the CSP and ctx.fetch), served at /app-frame/<app>/messageActions/<id>/…, inside a popover the host draws below the message. The popover's header names the app and the action, outside the frame. Escape, a press outside, the close button or another action closes it.

export function activate(ctx: {
  appName: string
  theme(): 'dark' | 'light'
  /** fetch() to this app's own backend routes; `path` is relative. */
  fetch(path: string, init?: RequestInit): Promise<Response>
}): {
  invoke(
    message: { text: string; format: 'plain' | 'markdown'; truncated: boolean; role: 'assistant' | 'user' },
    call: {
      invocationId: string
      /** Offer text for the host's Copy button (at most 32,000 UTF-16 units). */
      offerCopy(text: string): Promise<{ ok: true } | { ok: false; code: string }>
      /** Offer an https URL for the host's Open button. */
      offerOpen(url: string): Promise<{ ok: true } | { ok: false; code: string }>
      resize(size: { width: number; height: number }): void
      close(): void
      error(message: string): void
    },
  ): void
  cancel?(invocationId: string, reason: string): void // 'closed' | 'deadline' | 'other' | 'revoked'
  theme?(theme: 'dark' | 'light'): void
  dispose?(): void
}

One invocation per click. The host mints invocationId; the frame cannot make one. The invocation ends after 2 minutes without a resize or an offer, and when the popover closes, which the frame hears as cancel. Keep the call you were handed: an offer, resize, close or error for an earlier invocation is refused.

Copy and Open are the host's buttons. The frame cannot write the clipboard or open a window. It offers a value, and the host draws the button under the frame: Copy writes the clipboard only when the user clicks it; Open shows the host name and opens the URL in a new tab with noopener,noreferrer. An offer replaces the earlier one of its kind. Each offer is answered: { ok: true }, or { ok: false, code } with stale (another or a closed invocation, or a repeated offer), too_large or not_allowed (not copy or open, or not an https: URL).

A message over 64 KB of JSON, or past a burst of 120 messages refilled at 60 a second, is dropped unread. If the frame does not report ready within 10 seconds, or the module fails to import, or activate throws or returns no invoke, the popover says the app didn't open. An error shows that the app couldn't finish.

contributes.linkOpen — Open a Claimed Link in the App

A link-open entry lets the user open a link in a chat message inside the app, instead of a new browser tab. The host owns the click and the choice; the app owns what it shows, in the same sandboxed frame a link preview uses. No app code runs until the user picks the app.

{
  "contributes": {
    "linkOpen": [
      {
        "id": "open",
        "entry": "dist/link-open.mjs",
        "hosts": ["tickets.example.com", ".example.dev"]
      }
    ]
  }
}
Field Type Description
id string Storage-safe slug, unique within the app
entry string ESM module, relative to ui/ (same base as ui.entry)
hosts string[] 1-64 hostnames, with the same rules as linkPreviews.hosts. Only https: links on the default port and without a user name match
fullUrl boolean Optional. open gets the URL without its query and fragment unless this is true and the owner approved it

At most one entry per app; a click goes to the first enabled app whose hosts claim the link.

Which clicks. A plain left click on an https: link in a chat message whose host the entry claims. A click with Ctrl, Cmd, Shift or Alt, a middle click, a link outside a chat message and a link no app claims all behave exactly as before. So does a link to the dashboard itself (an artifact or a session), even when the dashboard is served at a host the entry claims.

The choice. The first click asks: open the link in the app, or in the browser. With Always checked the answer is remembered for this entry and this one host only, not for every host the app claims. A remembered "browser" makes the link an ordinary link again. The app's page lists the remembered answers, each with Forget.

Approval. The hosts and fullUrl are part of what the owner approves, like linkPreviews: an update that adds a host or turns fullUrl on waits on the app's page until the owner approves it. With no host approved the entry is off: no frame, no capability, no fetch.

Where the module runs. In a host dialog, in a frame created when the user picks the app and removed when the dialog closes. It is the shared app frame: opaque origin, credentialless, the same CSP and ctx.fetch as a link preview. The dialog's header has one More actions menu beside close. It always holds Open in browser, which is the host's own and always works.

export function activate(ctx: {
  appName: string
  theme(): 'dark' | 'light'
  /** fetch() to this app's own backend routes; `path` is relative. */
  fetch(path: string, init?: RequestInit): Promise<Response>
}): {
  // One call per open. Draw the link, then return; throw to fail it.
  open(link: {
    url: string                 // no query or fragment unless `fullUrl` was approved
    theme: 'dark' | 'light'
    invocationId: string        // the host's id for this open
    deadlineMs: number          // how long the host waits for open() to settle
    resize(size: { width: number; height: number }): void
    close(): void               // the app is done: the host closes the dialog
    error(message: string): void
    offerCopy(text: string): Promise<{ ok: boolean; code?: string }>
    offerOpen(url: string): Promise<{ ok: boolean; code?: string }>  // https only
  }): void | Promise<void>
  cancel?(invocationId: string, reason: string): void
  theme?(theme: 'dark' | 'light'): void
  dispose?(): void
}

Each open is one invocation on the shared invocation contract. When open() settles, the frame reports its size, which tells the host the link is drawn: the frame is shown and the deadline stops. When open() throws, or link.error() is called, the open fails. If neither happens within the deadline (10 seconds after the module is ready), the host cancels the invocation (cancel(id, 'deadline')) and shows "couldn't open this link" with Open in browser; a frame that does not report ready within 10 seconds, or whose module fails to import, shows the same. Closing the dialog first calls cancel(id, 'closed'). offerCopy and offerOpen put a Copy or Open <host> item in that menu: nothing is copied or opened until the user picks it. Links inside the frame open through the dashboard's link bridge.

contributes.composerActions — Buttons That Put Text in the Composer

A composer action is a row in the chat composer's + menu. When the user clicks it, the app's frame opens in a small popover above the composer, and the app hands back text. The host puts that text into the empty composer, where the user can read it, edit it and send it. The app never sends a message.

{
  "contributes": {
    "composerActions": [
      {
        "id": "insert-snippet",
        "title": "Insert snippet",
        "icon": "Zap",
        "entry": "dist/composer.mjs",
        "popover": { "width": 360, "maxHeight": 320 }
      }
    ]
  }
}
Field Type Description
id string Storage-safe slug, unique within the app
title string The row's label, at most 40 characters. The row also shows the app's name
icon string Optional host glyph name: one of Shield, Bot, Search, Tag, Users, Zap, Star, Package, Cat, AudioLines, Mic. Any other name falls back to Package; a URL is refused
entry string ESM module, relative to ui/ (same base as ui.entry)
popover object Optional. width 200-480 and maxHeight 120-600, in CSS pixels

At most two actions per app. A field of the wrong type, or a field not in this table, is refused at install. The block is signed.

What the app sees. Nothing from the composer: not the draft, not the selection, not the session. The click is the whole input. An app that needs the user's words asks for them in its own popover.

Approval. Each action is part of what the owner approves for the app. An update that adds an action waits on the app's page until the owner approves it; renaming one or changing its icon needs nothing. A disabled app, or an action whose approval is withdrawn, loses its row, and an open popover is closed.

Where the module runs. In the same sandboxed, opaque-origin frame as a link preview (see contributes.linkPreviews), loaded from /app-frame/<app>/composerActions/<id>/…. The module exports activate(ctx), which returns an invoke(call) handler. The host calls it once per click.

export function activate(ctx: {
  appName: string
  point: 'composerActions'
  theme(): 'dark' | 'light'
  /** fetch() to this app's own backend routes; `path` is relative. */
  fetch(path: string, init?: RequestInit): Promise<Response>
}): {
  // Nothing from the composer is passed in: only this click's own controls.
  invoke(call: {
    invocationId: string
    deadlineMs: number        // how long the click has, restarted by each resize
    signal: AbortSignal       // aborted when the user closes the popover, or at the deadline
    // Settles with { ok: true } when the host took it, or { ok: false, code }
    // (`stale`, `too_large`, `not_allowed`, `not_empty`, `not_literal`) when it refused.
    insert(text: string): Promise<{ ok: boolean; code?: string }>
    resize(size: { width: number; height: number }): void
    close(): void
    error(message: string): void
  }): void | string | Promise<void | string>  // returning text is the same as call.insert(text)
  theme?(theme: 'dark' | 'light'): void
  dispose?(): void
}
  • One result. The host takes one insert per click. A later one, one after the popover closed, or one over 32,000 characters is refused (insert settles with ok: false and stale or too_large).
  • Time. The frame must load and report ready within 5 seconds. The click then has 2 minutes, restarted by each resize; at the deadline signal aborts and the popover says the app took too long.
  • Only into an empty composer, only text with nothing to resolve. The host puts your text in only when the composer is empty (no text, no collapsed paste), so your text is the whole draft. If the user clicks with a draft already there, the popover says the draft must be cleared first and your frame is not loaded. If the user types while your frame is open, your insert settles not_empty. If another tab takes the composer's typing lock, your frame is closed and a late insert settles stale. Text that would itself be read as more than text is refused and nothing is inserted (not_literal): a line whose first non-blank character is / or ! (a terminal command), an @ that does not follow a letter or digit, a $ before a letter or digit, the composer's [ Paste #N · M lines ], [attached_file N] or [attached_dir N] syntax however it is spaced, markdown image syntax ![…](…), any raw HTML tag such as <img> (the transcript fetches a local image, audio or video destination, decoded), or a path separator followed on the same line by an image suffix. The popover shows the reason and stays open, so you can offer other text. Accepted text is cleaned of control characters (but tab and newline), bidirectional override characters and characters that draw nothing (zero-width, tag characters, variation selectors) and goes in as ordinary text the user can read and edit. Nothing marks it: whatever the user types after it is their own and resolves normally.
  • Limits. The frame cannot write the clipboard. Links open through the dashboard's link bridge, and a frame that navigates itself away is closed. A message over 64 KB as JSON, or past a burst of 120 messages refilled at 60 a second, closes the frame.

contributes.selectionActions — Items on Selected Chat Text

A selection action adds an item to the toolbar that appears over text the user selects in a chat reply. When the user picks it, the app is handed the selected text and nothing else, in a sandboxed frame that opens in a popover. Selection elsewhere in the dashboard never reaches an app.

{
  "contributes": {
    "selectionActions": [
      {
        "id": "save",
        "title": "Save to notes",
        "icon": "Star",
        "entry": "dist/selection.mjs",
        "maxLength": 4000,
        "effects": ["copy", "open"],
        "popover": { "width": 360, "maxHeight": 480 }
      }
    ]
  }
}
Field Type Description
id string Storage-safe slug, unique within the app
title string 1-40 characters. The item's label
icon string Optional. A name from the host icon set (Star, Tag, Bot, …, as for an app's own icon); an unknown name draws the host's glyph
entry string ESM module, relative to ui/ (same base as ui.entry)
sources string[] Optional, default ["chat"]. Where a selection may come from; chat (a chat reply) is the only source
minLength integer Optional, default 1. A shorter selection shows a notice instead of opening the frame
maxLength integer Optional, 1-8,000, default 8,000. The most text the app is handed, in UTF-16 units; longer selections are cut and truncated is set
effects string[] Optional, default []. Which host buttons the app may fill: copy, open
popover object Optional. width 200-480 (default 360), maxHeight 120-600 (default 480)

At most two items per app. A field with the wrong JSON type is refused, never coerced. The block is signed.

Approval. Each item is one entry the owner approves for the app, like permissions.api: <id>:<sources>:<minLength>-<maxLength>:<effects>. Installing approves what is declared. An update that changes any of those fields (a new source, more text, a new effect) waits on the app's page until the owner approves it, and until then that item is not offered: no frame is made, and a live frame's capability stops renewing and its fetches are refused. A pick from a menu that was read before the change is refused too, before any text reaches the app. Removing an item needs nothing.

In the toolbar. One Apps button sits in its own row under Quote, Ask and Copy, so the host's row never grows. It appears only while some enabled app has an approved item, and also when the dashboard could not load its app list, so a failure never hides it silently. It opens a menu of every item, read fresh from the app list each time it opens; if that read fails, the menu says so and offers Retry. The menu scrolls when it is taller than the screen. Each item names its app in its tooltip and in the popover's header. On a touch device the native selection, its handles and its Copy callout are left alone: nothing listens for a long-press. The items sit in the toolbar docked above the composer, and the popover is a sheet at the bottom of the screen.

Where the module runs. On the shared app frame, like a link preview (see above), at /app-frame/<app>/selectionActions/<id>/…: an iframe that is sandbox="allow-scripts" with no allow-same-origin, credentialless, loading the gateway's frame document under its own CSP, made when the item is picked and removed when the popover closes. Its capability and its frame token are bound to that one item, so they reach nothing for another item or point. ctx is { appName, theme(), fetch }; ctx.fetch reaches the app's own routes as for a link preview. The module exports activate(ctx) and returns a handler:

export function activate(ctx) {
  return {
    async invoke(selection, call) {
      // selection: { text, truncated, source: 'chat' }
      const res = await ctx.fetch('notes', { method: 'POST', body: JSON.stringify({ text: selection.text }) })
      const { url } = await res.json()
      document.body.textContent = 'Saved'
      call.resize({ height: 80 })
      await call.offerOpen(url)          // the host draws "Open notes.example.com"
      const { ok } = await call.offerCopy(url)   // the host draws "Copy"
    },
    cancel(invocationId, reason) {},     // reason: 'closed', 'deadline' or 'revoked'
  }
}

call belongs to one invocation:

Member What it does
invocationId The host's id for this pick
offerCopy(text) Offers at most 32,000 UTF-16 units for the host's Copy button. Resolves { ok: true } when the host accepted it, or { ok: false, code } with stale, too_large or not_allowed
offerOpen(url) Offers an https: URL (at most 2,048 characters, no userinfo) for the host's Open button, which names the host and opens a new tab with noopener,noreferrer. Resolves like offerCopy
resize({ height }) The frame height; clamped to 48 and popover.maxHeight
close() Ends the invocation and closes the popover
error(message) Ends the invocation and shows the message, as plain text, in host chrome

The invocation. Each pick is one invocation with a host-made invocationId the frame cannot make. It ends once: the frame closes it, reports an error, or the host cancels it (the popover closed, the app went away, or 2 minutes passed with no resize or offer). Every offer names its invocation and a rising seq and is answered with an acknowledgement or an error, so an offer for a closed invocation, a repeated one, or one of an undeclared kind does nothing. A later offer of the same kind replaces the earlier one. The frame never writes the clipboard or opens a window: an accepted offer only fills the host's button, which acts on the user's click. A link clicked inside the frame goes nowhere; use offerOpen.

Bounds. A frame that does not activate within 10 seconds, sends a message over 64 KB or past its burst allowance, or navigates itself away is removed, and the popover says the app did not respond.

backend — App Backend Process

{
  "backend": {
    "entryPoint": "backend/server.py",
    "port": "auto",
    "healthCheck": "/health",
    "routes": "/api/apps/oncall-watchtower"
  }
}
Field Type Default Description
backend.entryPoint string Script to run (relative to app root), or a dotted Python module path launched via python -m (used by built-in apps like file-explorer, e.g. kiro_crew.apps.builtins.file_explorer.server)
backend.port string "auto" Port number or "auto" for auto-assignment
backend.healthCheck string "/health" Absolute health-check path beginning with /; unsafe or ambiguous paths are refused. Polled until it answers at startup, then re-polled for the life of the backend — keep the handler cheap and dependency-free. A backend that stops answering it is dropped from the reverse proxy and its MCP servers are deregistered until it answers again. The route must answer an UNSIGNED loopback GET directly with a 2xx — the probe sends no proxy credential and follows no redirect, so a path behind the backend's own auth (401/403) and a path that redirects (3xx) both fail forever and the app never becomes reachable (the gateway then returns app '<name>' has no reachable backend). The gateway log names the observed status.
backend.routes string Base route path for the backend
backend.type string "" Backend runtime: "python", "asgi", "node", "exec" (execute the entry point file as-is), or "" (auto-detect from entryPoint — a .sh file or an extensionless executable with a non-Python shebang is treated as a shell launcher)
backend.signedPrincipal boolean false Add a signed X-KiroCrew-Principal claim to every request the reverse proxy forwards to this backend. Only the JSON boolean true turns it on. The claim says whether the gateway authenticated an owner-session, an app-token, an agent-tool call, or none.

Note: the shell-launcher auto-detect reads the entry point's shebang line, so a compiled/binary launcher (e.g. an ELF executable) cannot be auto-detected — declare "type": "exec" explicitly for those. Exec backends are POSIX-only: on native Windows the backend is refused at spawn with a logged error (use a Python or Node entry point instead). The enable, install and update responses then carry a backend_refused field with that reason; the app itself still enables, since its other parts do not need the backend.

App backends are accessible through the Gateway's reverse proxy at /apps/{name}/api/{path}, which avoids CORS issues for dashboard UI pages.

backend.signedPrincipal grants the app no new access. It passes on an identity the gateway already authenticated. Only a request that a dashboard session cookie authenticated for the dashboard owner receives owner-session and an owner id. App tokens, internal agent and MCP tool calls, crons and ?token= link exchanges never receive that kind. The header format and the verification steps are in the API reference under Signed principal claim.

backend.hooks — In-Gateway Python Entry Points

Instead of (or alongside) a standalone backend process, an app can register Python entry points that run inside the Gateway process. Each value is a dotted path in the format module.path:callable, resolved relative to the app root (validated against HooksConfig._HOOK_PATH_RE).

{
  "backend": {
    "hooks": {
      "routes": "backend.routes:register_routes",
      "on_startup": "backend.hooks:on_startup",
      "on_shutdown": "backend.hooks:on_shutdown"
    }
  }
}
Field Type Description
backend.hooks.routes string module.path:callable that registers handlers into the Gateway's in-process RouteRegistry catch-all dispatcher
backend.hooks.on_startup string module.path:callable invoked when the app's hooks are wired up
backend.hooks.on_shutdown string module.path:callable invoked when the app is disabled/torn down

The routes callable receives the app context and returns a list of routes. Each route is any object with three attributes, so the app declares its own dataclass and never imports kiro_crew:

from dataclasses import dataclass
from typing import Any, Callable

@dataclass(frozen=True)
class Route:
    method: str        # GET, POST, PUT, DELETE or PATCH (any case)
    path: str          # relative to /api/apps/<app>/, at most 512 characters
    handler: Callable  # async (request, ctx) -> response

def register_routes(ctx):
    return [Route("GET", "/items", list_items), Route("POST", "/items/{item_id}", save_item)]

An item whose method is not one of those five, whose path is not a string of at most 512 characters, or whose handler is not callable is skipped with a warning. The built-ins' AppRoute class is still accepted.

hooks.routes handlers are wired up when the app is enabled through the Gateway -- the dashboard's enable action (on_app_enable), also re-run at gateway startup (on_gateway_startup) -- so on that path they go live without waiting for a Gateway restart.

kirocrew app enable and kirocrew app disable apply live when a running Gateway is reachable through the CLI's owner-only Unix socket (POSIX only), including starting or stopping the backend. Otherwise the CLI records the change for the next Gateway start. On that file-only path, enabling an app that declares backend.hooks also prints the hooks reminder so the delayed activation is explicit.

Importing your own modules. Hook entry files are loaded from their file path into a synthetic package named after the app, never via sys.path, so use a relative import to reach a sibling module:

# backend/routes.py
from . import config          # backend/config.py
from .render import to_html   # backend/render.py

A relative import resolves inside the app's own directory tree and cannot walk above the app root (from ... import x is refused). It is not a sandbox: app Python already runs in the Gateway process with full filesystem access, so a symlinked sibling resolves wherever it points. Do not use a bare import config: sys.modules["config"] is process-global, so two apps each shipping a config.py would end up sharing one module. from kiro_crew... absolute imports are for built-in apps only; an installed app reaches the host through its context (ctx.require_owner, ctx.embed, ctx.scrub and the other context members).

Python dependencies. Runtime requirements.txt provisioning — the data/.kirocrew-deps/ tree described in the stdio command-resolution passage above — runs only where app code executes as its own process: the backend.entryPoint spawn path (a real file entry point in the app's own tree) and stdio MCP server registration. Hook code gets nothing from it: the tree reaches processes spawned on the app's behalf — through a site-processing launch shim for Python commands, on PYTHONPATH for ABI-matched others — and is never placed on the Gateway's own import path, because hooks run inside the Gateway process, where an app-controlled tree ahead of the trusted modules could shadow the Gateway's own code. That is the same rule that keeps -m kiro_crew... servers off the app deps, and it binds your hook code too: do not push your own tree onto sys.path ahead of the Gateway's modules from inside a hook.

What serves hooks instead is the install-time build step: a registry install (which clones the app's git source) runs pip install . (or pip install -r requirements.txt when there is no pyproject.toml/setup.py) into the Gateway's own interpreter — the one that imports your hooks (see the publishing guide's install flow) — but only when the app's source directory (the subdirectory when one is declared) has no package.json, which takes precedence and routes the build to npm instead. Two caveats: a failed pip run fails the install, and the desktop app's bundled interpreter cannot be installed into at all — it lives inside the signed application bundle, so on that build the step is refused with a loud error for anything that would have to land in the Gateway's interpreter (pyproject.toml, setup.py). A Gateway interpreter with no pip module instead logs a soft skip, so an app that truly requires those dependencies must detect their absence rather than assuming the build ran. An app installed by other means, one whose package.json routed the build to npm, or one declaring no requirements.txt/pyproject.toml/setup.py at all, imports only the stdlib plus whatever the Gateway's environment already provides.

The one desktop exception is a root requirements.txt that the runtime provisions itself, and it is exactly the runtime's own condition: the app declares an out-of-process consumer in a shape the runtime provisions for — a Python script backend.entryPoint (server.py, backend/app.py: a .py file, the one child the provisioned deps tree reaches), or a stdio mcpServers entry (one without url) — and declares no backend.hooks. A shell or node entry point (run.sh, server.js) is not that consumer: the runtime installs the file beside it at spawn, but hands the tree only to a Python child — through the deps_boot shim or PYTHONPATH — so such an app keeps the refusal unless a stdio server is the consumer. A module-style, dotted entry point (my_pkg.server) is trusted package code the runtime never installs an app-directory requirements.txt for, so it keeps the refusal rather than passing an install whose dependencies would land nowhere. Those dependencies are not the Gateway's to import: the entry point runs as its own process, a stdio server is spawned as its own process, and the runtime provisioning above installs that same file into the app's own deps tree when the backend spawns or the server is registered — so the install-time step is SKIPPED (not refused, and no pip runs) and the runtime owns it. The refusal still applies to that app's pyproject.toml/setup.py, to a requirements.txt sitting beside either of them, to an app that declares neither consumer (nothing would ever provision the file), to an app that ALSO declares a hook — a hook is imported into the Gateway process, which the deps tree never reaches, so its imports would be broken by an install that reported success — and to a self-managed registry entry (resources: "app"), whatever its manifest declares: such an app is registered from its manifest alone (no source is copied into the app directory, the Gateway spawns and registers nothing for it, it launches itself), so neither provisioner ever runs for it and only the install-time step would have installed the file. "Declares a hook" is read from the same normalized manifest the Gateway's own loaders are handed, so a hooks value the manifest parser drops is not one. The requirements.txt itself must be what the runtime will read: a regular file, or a symlink that resolves to a regular file inside the app directory (requirements.txt -> requirements/prod.txt is fine); a link that leaves the directory, or a dangling one, is refused at spawn and therefore refused here too. And "here" is the app directory, not the checkout: the gate judges an actual copy of the checkout made by the install's own copy step, so whatever that step drops, omits, keeps or rewrites is already applied to the tree it reads. A link whose target the copy does not carry — under data/, which an update replaces with your preserved data (a root entry named data never survives an install verbatim in either shape — nor Data where the filesystem folds case, as the desktop's usually do — and a root data that is a link, whatever it points at, or a regular file is refused outright before anything is installed: the Gateway moves that directory aside and back across updates, and a relocated link would lose the directory it named), at .app_secret, which the Gateway removes — a shipped file or link alike, the link never followed — before writing its own credential there, or under a name the copy drops at any depth (node_modules, .venv, .git, __pycache__), a regular file so named included, since the copy drops by name whatever the entry's type — dangles in that copy and is refused; a link whose text climbs above the directory and re-enters it by naming the checkout (../../app-sources/<name>/requirements/prod.txt) resolves in the checkout, points outside the copy, and is refused; a directory named requirements.txt is nothing the runtime can read and is refused too. The same holds for the entry point itself: a backend.entryPoint that is not a regular file inside that copy — under data/ or a dropped name, by its declared path or by where a link resolves, a directory standing where the file should be — does not qualify. The verdict is derived twice from the same rule: once before the build, and again on the final checkout after setup.onInstall has run — a script that adds a hook or removes the consumer the exception was granted for fails the install with the same refusal (an entry file or a link target that does not exist yet — nothing at the path, or a link pointing at a target your script has yet to create — is let through by the first pass and refused by the final one if it never appeared; anything else standing at the path is refused by both), and the checkout is rolled back as for any other post-script rejection. A checkout the final pass cannot even copy for its verdict — your script left something the copy cannot read, such as an unreadable file, a FIFO or a symlink loop — is rolled back the same way and the install fails with the copy's error, not with the desktop refusal, so a retry starts clean. Build files (pyproject.toml, setup.py, requirements.txt, package.json) that appeared while the script ran leave the checkout, each named in the install log, so a corrected retry is not refused by them: on a checkout that already existed they are set aside beside it, in a <name>.stale-… sibling under app-sources that the retention sweep removes after seven days (recoverable from the path the log names until then); a checkout created by the failed install is deleted whole, and they go with it. Files that predate the script, tracked or not, are never touched. On a source install nothing changes — requirements.txt is still pip-installed at install time — so an app that needs its dependencies importable by hooks must ship pyproject.toml/setup.py and accept that it cannot install on the desktop build.

If you create a directory to hold your own dependencies, do not name it .venv. Interpreter resolution (resolve_app_python) runs only for spawned surfaces — a backend entry point or a stdio MCP server — so a purely hooks-only app never triggers it; but the moment your app also declares one of those (now or in a later version), a real, probe-usable virtual environment at <app>/.venv becomes the interpreter for anything spawned on the app's behalf whenever no provisioned deps tree is active, even when it holds no packages at all.

Permissions

permissions — Declared Capabilities

{
  "permissions": {
    "api": ["/api/crons", "/api/status", "/api/agents"],
    "events": ["notification", "slots"],
    "mcpTools": ["cron_add", "cron_list"],
    "storage": true,
    "cron": true,
    "memory": "app-scoped",
    "network": false,
    "sessionApproval": false,
    "spawn": false,
    "jobs": false,
    "proposeCrewmate": false,
    "exposeToApps": []
  }
}
Field Type Description
permissions.api string[] Allowed API path prefixes. /api/member-records/* is the one that lets the app put a value on a Dashboard page of ANY crewmate it names by slug; there is no per-crewmate form of the grant (api-reference)
permissions.events string[] Allowed WebSocket event types
permissions.mcpTools string[] Allowed MCP tool names
permissions.storage boolean Can use app-scoped storage
permissions.cron boolean Can create cron jobs at runtime (ctx.cron). Required when crons is non-empty
permissions.memory string Memory access: "" (none), "app-scoped", or "shared"
permissions.network boolean Can make external network requests
permissions.sessionApproval boolean Controls existing local user sessions: send messages (including generated response-option choices, but not a change to the session's agent binding, persona settings, or a harness slash command), approve or deny pending tool requests, and change approval modes within the limits below
permissions.spawn boolean May start a background agent through the host's subagent manager (ctx.spawn)
permissions.jobs boolean May run durable background work through ctx.job and the app-owned _jobs/* routes
permissions.proposeCrewmate boolean Preview, switched off: ctx.crewmate stays None until the owner view that lists the cards lands (#21718). May propose one crewmate from a .crewmate bundle through ctx.crewmate. Gates a real capability like spawn: ctx.crewmate is absent unless the value is literally true. Each proposal is an owner change card; only the owner's press creates the crewmate (api-reference)
permissions.exposeToApps string[] App names (or "*") allowed to request cross-app visibility into this app's slots/subagents

permissions.spawn — Background Agents

Unlike the advisory fields above, this one gates a real capability: ctx.spawn is absent from the app context unless the manifest declares it, so an app that did not ask cannot start an agent even by importing the SDK. Declared rather than inferred so "which apps can start an agent" is answerable from the manifest instead of from an app's import graph.

Spawns run through the HOST's subagent manager, which means they inherit the host's spawn accounting and approval mode rather than getting a private path. Cost is the app's to bound: an app that spawns on a timer needs its own budget (see the activity-budget pattern in builtins/mochi/activity_budget.py), because the platform does not rate-limit spawns per app today.

API: apps/spawn_sdk.py — SpawnSDK, build_spawn_impl, build_done_probe, SpawnError.

Not an in-process sandbox. Most fields remain advisory for app code loaded inside the gateway. The validator functions in apps/permissions.py (validate_permissions, format_permissions_summary) are still not wired into the install or runtime path; format_permissions_summary only feeds the kirocrew app enable refusal below. permissions.sessionApproval is shown on the app detail page and in the install or enable consent dialog, and only the dashboard grants it. kirocrew app enable has no consent flag or prompt: for an app whose consent is pending it prints what the app asks for and the app's dashboard link, exits 1 and leaves the app off. It is enforced for app-token user-session calls, in addition to permissions.api. The app must be enabled. The grant reaches existing local user-owned sessions only; cron, system, remote, member-mode, and other apps' sessions are denied. Apps retain their pre-existing access to their own slots. On the per-slot routes (/api/chat/slots/{slot}/*) the grant reaches approving or denying a pending tool request only; every other per-slot route answers an app 404 slot_not_found unless the app owns the slot, whatever permissions.api prefix it holds. Mode changes must name a live allowed slot and are limited to Normal, Reads and Trust; YOLO is a process-global override and stays dashboard-only. An update that newly adds the flag disables the app until the user enables it again from the detail page, which shows why. An update that adds an entry to permissions.api or permissions.events keeps the app enabled but withholds the new entries until the user approves them on the detail page. Official catalog entries mirror this flag so users see it before install even when the store skips fetching the app manifest. Install-time path traversal is blocked separately by _check_path_safety(name) plus manifest.validate(). Full in-process enforcement is tracked in rfc-app-sandbox-isolation.md.

Notification channels

{
  "notifications": {
    "channels": [
      { "id": "sync-status", "name": "Sync status", "icon": "Bell", "defaultPriority": "passive" }
    ]
  }
}

notifications.channels declares up to eight app-owned channels. Each channel requires a unique kebab-case id and a display name; icon is optional and defaultPriority is critical, default, or passive (default default). Declarations are covered by the app admission signature.

Artifact publish provider

publishProvider contributes one destination to the artifact publishing UI:

Field Type Default Description
publishProvider.id string Stable provider id
publishProvider.label string User-facing action label
publishProvider.icon string Host icon name
publishProvider.endpoint string App-owned route that receives publish requests
publishProvider.kinds string[] [] Supported artifact kinds; empty means all
publishProvider.setupRoute string App UI route for configuration
publishProvider.configFile string "config.json" File beneath the app's data/ directory used for readiness detection
publishProvider.configuredField string Field that must be non-empty for the provider to count as configured

Only enabled apps contribute providers. Core reads configuration state and calls the endpoint; it does not import provider code.

Setup Hooks

setup — Lifecycle Scripts

{
  "setup": {
    "onInstall": "cd ui && npm install && npm run build",
    "onUninstall": "echo cleanup done",
    "onEnable": "echo enabled",
    "onDisable": "echo disabled",
    "configSchema": {}
  }
}
Field Type Default Description
setup.onInstall string "" Shell command run during a registry install and again on every registry update (an update re-enters the install transaction), after clone/build and before the installed copy is created. Not run for a local-path install. Make it idempotent
setup.onUninstall string "" Shell command run before uninstall
setup.onUpdate string "" Declared and preserved in the manifest but not executed — no code path dispatches it. Put update-time work in an idempotent onInstall, which a registry update re-runs
setup.onEnable string "" Shell command run when app is enabled
setup.onDisable string "" Shell command run when app is disabled
setup.onEnableTimeout number 30 Timeout in seconds for onEnable script, 1 to 300. A numeric string such as "60" is read as its number and a fraction is truncated. A value below 1 (including false) runs at the 30s default; true is read as 1 second and one above 300 runs at 300, with a warning logged each time the script runs; the manifest still installs and its signature is unaffected. A value that is not a number ("abc", null) fails validation
setup.onDisableTimeout number 30 Timeout in seconds for onDisable script, 1 to 300, clamped the same way as onEnableTimeout
setup.configSchema object {} JSON Schema for app configuration

If onEnable fails (non-zero exit), the enable is rolled back — the app stays disabled and any registered resources are deregistered. onDisable failures are logged as warnings but do not block the disable operation. Local-path installs do not run onInstall; build first, then install. The onEnable, onDisable and onUninstall hooks always invoke /bin/bash, so they are not run on native Windows (which has no /bin/bash): the runner refuses the hook before any process is started and reports a failure whose message names the unsupported platform, rather than letting the spawn fail opaquely and look like your script breaking. onInstall also runs through /bin/bash and gets the same up-front refusal: a registry install or update of an app that declares it fails on a native-Windows host with an error naming the unsupported platform, before the script is started. Write hooks for POSIX shells; do not rely on them running on a native-Windows host.

Exception — platform.installMode: "client" apps. For a client app the script is advisory: a failure is reported on the response as onEnable.failed but the app stays enabled, and the script is skipped entirely (onEnable.skipped: "unsupported_platform") when the gateway's OS is not in the app's platform.os. Such an app's real payload is a desktop application the user installs on their own machine, so its script addresses something that may legitimately be absent here — rolling back would make the app's dashboard half impossible to enable on exactly the hosts that need it to explain how to get the desktop half.

Install scripts run in a sandboxed environment with a minimal set of environment variables (PATH, HOME, SSH_AUTH_SOCK, etc.) to prevent leaking secrets from the gateway process.

Dependencies

dependencies — External Dependency Declarations

Declare external dependencies your app requires. The gateway tracks these in a reference-counted ledger so shared dependencies are not removed when only one app is uninstalled.

{
  "dependencies": {
    "managedBy": "gateway",
    "capabilities": {
      "mcp": [
        { "id": "some-mcp-server" }
      ],
      "skills": [
        "some-skill"
      ],
      "agents": [
        { "id": "some-agent", "managedBy": "app" }
      ]
    },
    "commands": ["jq", "node", "python3"]
  }
}

Each capability entry is a string id or an object { id, managedBy }. An entry's own managedBy overrides dependencies.managedBy.

Field Type Default Description
dependencies.managedBy string "gateway" Who manages dependency lifecycle: "gateway" or "app"
dependencies.capabilities object {} Capability-package dependencies (MCP servers, skills, agents) resolved through the edition's capability manager. The open-source edition ships none, so these entries are reported as unresolved (they appear in the install result's failed list) and the app still installs — design for graceful degradation.
dependencies.capabilities.mcp object[] [] Required MCP server dependencies
dependencies.capabilities.skills object[] [] Required skill dependencies
dependencies.capabilities.agents object[] [] Deprecated for managedBy: "gateway" — no capability-manager install operation exists for agents in any edition, so a gateway-managed entry can never succeed and is always reported unresolved. Declare managedBy: "app" (or install out of band) instead.
dependencies.commands string[] [] Required system commands checked on PATH; misses are reported but do not block install
dependencies.optionalCommands string[] [] Optional commands checked and reported separately as missingOptional

The former dependencies.aim key is still accepted as a deprecated alias, but it is never written back — a manifest round-trip migrates it to dependencies.capabilities. Use capabilities in new manifests.

Lifecycle & Resource Management

lifecycle and resources

Control how Kiro Crew manages the app:

Field Type Default Description
lifecycle string "gateway" "gateway" (managed), "app" (self-managed), or "locked" (cannot uninstall)
resources string "gateway" "gateway" (Kiro Crew registers agents/skills/MCP) or "app" (app handles its own)

Platform

platform — Compatibility & Install Mode

{
  "platform": {
    "os": ["macos", "linux"],
    "arch": [],
    "requiresDesktopApp": false,
    "installMode": "server",
    "clientInstall": {
      "shell": "curl -fsSL https://example.com/install.sh | bash",
      "postInstall": "open ~/Applications/MyApp.app"
    }
  }
}
Field Type Default Description
platform.os string[] ["macos", "linux"] Supported platforms. Valid names: macos, linux, windows; any other value is rejected at validation. The default excludes windows — see below
platform.arch string[] [] (any) Supported architectures
platform.requiresDesktopApp boolean false App's own UI needs the Electron desktop shell
platform.installMode string "server" "server" or "client"; any other value is rejected at validation
platform.clientInstall.shell string One-liner for local install
platform.clientInstall.postInstall string Command to run after install

platform.os — a published claim, and silence publishes "no"

For a server-mode app (every builtin), platform.os is a user-facing CLAIM, not an access control. It is rendered on the App Store detail page (website/src/pages/AppDetailPage.tsx), and that is its only non-test consumer. apps/routes_enable.py reads it once, via _client_install_manifest(), which returns None unless platform.installMode == "client"; handle_enable_app's docstring states the rest outright — "nothing else on the enable path consults that field". So omitting the block does not stop the app being enabled anywhere.

What it does do is publish something untrue. The default is ["macos", "linux"], so an app that omits the platform block tells every Windows user that it does not run there — indistinguishable from a deliberate statement, and wrong if the app in fact runs fine.

Declare the block explicitly and make it say what you mean:

{ "platform": { "os": ["macos", "linux", "windows"] } }

For a platform.installMode: "client" app the field DOES gate behaviour: the onEnable script is skipped with onEnable.skipped: "unsupported_platform" when the gateway's OS is not listed, because that script addresses a separately distributed desktop application.

Two things decide whether your app can honestly claim windows:

  1. Does its code assume POSIX? Route every platform decision through kiro_crew.platform_compat (IS_WINDOWS, IS_POSIX, file_lock, rename_noreplace, trusted_system_bin, …) rather than writing a raw sys.platform test. Pass explicit encoding="utf-8" on text I/O — the Windows default code page is not UTF-8. Prefer os.replace over os.rename, and reject Windows-reserved file names (CON, NUL, COM1–COM9, LPT1–LPT9, and names ending in a dot or space).

  2. Does it need a backend CHILD PROCESS? An app with no backend, or with backend.hooks only, runs inside the Gateway process and spawns nothing, so it is unaffected by the item below. An app with a backend.entryPoint is spawned through sandbox.wrap_argv without the first-party carve-out, and Kiro Crew has no native Windows sandbox backend — so on native Windows that spawn runs unconfined under this platform's default, since no backend is installable here; it is refused only where the operator declared agent.sandbox_allow_unsandboxed_exec=false or a governance sandbox.min_level floor is pinned. Say so in your app's configuration copy rather than publishing "does not run here", so a locked-down host is not a surprise. See docs/guides/windows-install.md and docs/system-specs/common/platform-compat.md.

When installMode is "client", the App Store shows copy-paste terminal instructions instead of running the install on the server. This is used for apps that must run on the user's local machine (e.g. Electron desktop apps when Kiro Crew runs on a remote host).

platform.requiresDesktopApp — Desktop-Only UI

Declares that the app's OWN interface needs the Electron shell (a transparent always-on-top window, a tray surface, global shortcuts — things a browser tab cannot provide). A different axis from os: os says which machines the app can run on at all, this says which CLIENT can render it.

It gates rendering, not enabling. Enabling is a server-side state change — the app's backend, hooks, agents and crons all run in the gateway — so a browser user can still turn the app on and its autonomous side works. Only the app's own window is unavailable. The App Store therefore keeps the Enable action in a browser and shows a "Desktop app" hint beside it (AppListRow, FeaturedSpotlight, AppDetailPage); replacing the button with a static claim left remote users with no way to enable the app at all.

UX gate, not a security boundary. The marker is evaluated client-side (lib/electron.ts::needsDesktopApp), so it must never be the only thing standing between a caller and a capability. Anything that must not happen in a browser belongs behind an app-token scope or a server-side check.

Open Command

openCommand — Launch Apps Outside the Dashboard

For apps that run outside the dashboard (e.g. Electron apps), the top-level openCommand declares a shell string that launches the app.

{
  "openCommand": "open ~/Applications/MyApp.app"
}
Field Type Default Description
openCommand string "" Shell command launched by POST /api/apps/{name}/open

POST /api/apps/{name}/open runs this command in the background. On a cloud/remote environment with no display, the endpoint returns the command for the user to run locally instead of executing it on the server. On native Windows, which has no /bin/sh, the command is not run: the endpoint answers 409 with code: "app_open_unsupported_platform" and an error naming the platform. The same refusal covers a registry entry's detectInstalled probe, which reads not-installed there and logs one warning.

openCommand — Environment

The command runs as /bin/sh -c "<openCommand>" under the standard sandbox tier and the cgroup resource ceiling, with an allowlisted environment — not the gateway's. An installed app is untrusted content, so the launcher gets the same allowlist the manifest's install and build commands get, plus the location hints a desktop launch needs:

  • The allowlist (_SAFE_ENV_KEYS / minimal_env in src/kiro_crew/apps/registry_pipeline/subprocess_env.py — that source file is the list): shell and locale basics such as HOME and PATH, the XDG directories (including XDG_RUNTIME_DIR), toolchain roots (Java, Node, Python, Conda, Gradle/Maven), the git SSH overrides, and the Windows equivalents of the basics. Proxy and CA-bundle variables (HTTPS_PROXY, NO_PROXY, SSL_CERT_FILE, ...) are not on it: only the gateway's own git clone, fetch and pull of app and registry repositories receive them, because a proxy URL can carry a password.
  • Removed again before the spawn (sandbox.scrub_env): of the allowlisted names, the SSH agent socket SSH_AUTH_SOCK. The install and build commands run git against the owner's own repositories and need it; a launcher does not, and an app-authored shell holding it authenticates as the operator. The scrub's other targets (AWS_SECRET* / AWS_SESSION*, GNUPGHOME, GIT_ASKPASS, the gateway's channel credentials) are not in the allowlist to begin with.
  • Desktop hints copied on top, each only when the gateway itself has it: DISPLAY, WAYLAND_DISPLAY, XAUTHORITY, DBUS_SESSION_BUS_ADDRESS, XDG_SESSION_TYPE, XDG_CURRENT_DESKTOP.

The two user-bus locators, XDG_RUNTIME_DIR (from the allowlist) and DBUS_SESSION_BUS_ADDRESS (from the desktop hints), reach the child on this path. The sandbox's restore-then-drop of those two variables applies to spawns that go through sandbox.sandboxed_spawn_argv; openCommand does not. Whether a standard-mode launcher should hold a live user-bus address at all is under review in #16520 — do not build a launcher that depends on DBUS_SESSION_BUS_ADDRESS being set. XDG_RUNTIME_DIR is not in question: it is where the Wayland socket lives.

Anything not listed above — the gateway's own model credentials, API keys you exported in the gateway's shell, EDITOR, BROWSER, custom MYAPP_* variables — is absent. Set what your launcher needs inside the command string itself ("openCommand": "MYAPP_MODE=tray myapp"), or have the launcher read its own config file.

Failures are silent. The endpoint spawns the shell and answers {"ok": true, "pid": …} immediately; it does not wait, and the child's stdout and stderr go to /dev/null. A launcher that exits because a variable it expected is missing still shows as a successful launch in the dashboard, and the audit log records only app_open … launched — neither reflects the exit. If your launcher can fail, have it write its own log, and create the log directory first — a >> into a directory that does not exist makes sh exit before it runs your command, which is the same silent failure:

{
  "openCommand": "mkdir -p \"$HOME/.cache/myapp\" && myapp >>\"$HOME/.cache/myapp/open.log\" 2>&1"
}

Validation Rules

  • name must match /^[a-z0-9]+(?:-[a-z0-9]+)*$/ (kebab-case)
  • name must not be system (it would shadow the system.* notification-channel namespace)
  • name must not be library (the dashboard serves /apps/library as a static page — the installed-app management surface — and it registers ahead of the /apps/:name route, so an app by that name would have an unreachable page).
  • name must not be registry, registries, blob, install, or register; those are shared literal segments beneath /api/apps/, registered ahead of the per-app catch-all. These reserved-name refusals use the machine-readable error code reserved_app_name at every install door.
  • name must not be a Windows reserved device stem — con, prn, aux, nul, com1–com9, lpt1–lpt9 — because the app name becomes a directory and Windows resolves those inside every directory. Names that merely resemble one (console, com10, null-app) are fine. Refused on every platform: an app name is a persistent published identity, so it must mean the same thing on whichever host installs the app.
  • version must start with MAJOR.MINOR.PATCH; a pre-release (-) or build (+) suffix may follow it
  • Paths in agents, skills, sops, ui.entry, ui.pages[].entryPoint, contributes.sessionControls[].entryPoint, contributes.panelTabs[].entry, and backend.entryPoint must be relative and stay inside the app root: absolute paths and .. traversal are rejected (canonical resolve + containment when the app dir is known). backend.hooks.* are format-checked (module.path:callable, which cannot express traversal) and containment-checked again at load time. mcpServers entries use command/args/url/env. They are not path-checked at manifest load; at registration, when command is a bare python, python3 or py, a relative .py launch target is resolved against the app root when it is a file inside it (see "An app's own .py launcher" above).
  • All required fields must be non-empty strings
  • config_keys must be an array of at most 200 non-empty strings, each at most 200 characters long
  • Each cron entry must specify either every or cron_expr
  • A non-empty crons requires "cron": true under permissions. Install, update and self-registration refuse the manifest otherwise; an app already installed keeps loading and firing its crons until its next update
  • Each UI page must have route and label
  • Each UI overlay must have id and replaces; both must be kebab-case, and id must be unique within the manifest
  • Each platform.os entry must be exactly macos, linux or windows. Spelling and case matter: Windows, win and windows match no platform, so the platform gate would answer no for the platform the manifest names. The platform strings darwin and win32 are refused too
  • platform.installMode must be exactly server or client; the install gates test for client alone, so a spelling such as Client would install as a server app

Full Example

{
  "name": "oncall-watchtower",
  "version": "1.0.0",
  "displayName": "Oncall Watchtower",
  "description": "Monitor tickets, pipelines, and alarms for your on-call rotation",
  "author": "kirocrew",
  "tags": ["oncall", "monitoring"],
  "useCases": ["Keep a shared view of firing alerts and active investigations"],
  "configuration": ["Connect an alert provider in Settings, then start in read-only mode"],
  "screenshots": ["ui/screenshots/board.png"],
  "agents": ["agents/ticket-analyst.json"],
  "skills": ["skills/oncall-runbook"],
  "crons": [
    {
      "name": "ticket-refresh",
      "every": 300,
      "message": "Check for new high-severity tickets"
    }
  ],
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [
      {
        "route": "/apps/oncall-watchtower",
        "label": "Oncall",
        "icon": "Shield"
      }
    ]
  },
  "permissions": {
    "api": ["/api/crons", "/api/status"],
    "events": ["notification"],
    "cron": true
  },
  "platform": {
    "os": ["macos", "linux"]
  }
}

Forward Compatibility

Unknown fields in app.json are preserved during parsing and round-tripped through to_dict() / to_json(). This allows newer manifest features to coexist with older Kiro Crew versions without breaking validation.