The app manifest (app.json) declares your app's identity, resources, and requirements.
| 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 |
| 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 |
| 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.
| 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 |
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'srequirements.txt(apip install --targetintodata/.kirocrew-deps/; python launchers run through asite.addsitedirshim so.pthfiles are processed, other commands see the dir onPYTHONPATH; underdata/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.exeon 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 whoseargslaunch akiro_crewmodule (-m kiro_crew...) always gets the gateway's interpreter and never the app deps onPYTHONPATH, 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,dockerand 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
.pylauncher (a stdio server whosecommandis a barepython,python3orpy, and whose launch target is a relative path ending in.py, given inargsand 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. Acommandcarrying 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 incommanditself is still never rewritten. - The host CLI name
kirocrewis 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).
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 anenvvalue holding${NAME}or asecret://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.
{
"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": falsethat 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.
{
"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) |
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.
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.
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.
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.
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.
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.
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.
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 bundledui/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 directoryapp.jsonlives in: for a registry entry that declares asubdirectory, 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.
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
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 withlink.card.resize, and shows it withlink.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.dragBymoves it (usescreenX/screenYdeltas: the frame moves under the pointer) andcard.docksticks 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.setRegionsmakes 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, sorectis exactly where the link is. Card-mode calls are ignored, andhideis 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.
textPatternsis signed.
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.
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.
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
insertper click. A later one, one after the popover closed, or one over 32,000 characters is refused (insertsettles withok: falseandstaleortoo_large). - Time. The frame must load and report ready within 5 seconds. The click then
has 2 minutes, restarted by each
resize; at the deadlinesignalaborts 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
insertsettlesnot_empty. If another tab takes the composer's typing lock, your frame is closed and a lateinsertsettlesstale. 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.
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": {
"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 abackend_refusedfield 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.
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.pyA 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": {
"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 |
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_summaryonly feeds thekirocrew app enablerefusal below.permissions.sessionApprovalis shown on the app detail page and in the install or enable consent dialog, and only the dashboard grants it.kirocrew app enablehas 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 topermissions.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 app404 slot_not_foundunless the app owns the slot, whateverpermissions.apiprefix 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 topermissions.apiorpermissions.eventskeeps 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)plusmanifest.validate(). Full in-process enforcement is tracked in rfc-app-sandbox-isolation.md.
{
"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.
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": {
"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.
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.aimkey is still accepted as a deprecated alias, but it is never written back — a manifest round-trip migrates it todependencies.capabilities. Usecapabilitiesin new manifests.
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": {
"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 |
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:
-
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 rawsys.platformtest. Pass explicitencoding="utf-8"on text I/O — the Windows default code page is not UTF-8. Preferos.replaceoveros.rename, and reject Windows-reserved file names (CON,NUL,COM1–COM9,LPT1–LPT9, and names ending in a dot or space). -
Does it need a backend CHILD PROCESS? An app with no
backend, or withbackend.hooksonly, runs inside the Gateway process and spawns nothing, so it is unaffected by the item below. An app with abackend.entryPointis spawned throughsandbox.wrap_argvwithout 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 declaredagent.sandbox_allow_unsandboxed_exec=falseor a governancesandbox.min_levelfloor is pinned. Say so in your app'sconfigurationcopy rather than publishing "does not run here", so a locked-down host is not a surprise. Seedocs/guides/windows-install.mdanddocs/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).
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.
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.
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_envinsrc/kiro_crew/apps/registry_pipeline/subprocess_env.py— that source file is the list): shell and locale basics such asHOMEandPATH, the XDG directories (includingXDG_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 owngitclone, 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 socketSSH_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"
}namemust match/^[a-z0-9]+(?:-[a-z0-9]+)*$/(kebab-case)namemust not besystem(it would shadow thesystem.*notification-channel namespace)namemust not belibrary(the dashboard serves/apps/libraryas a static page — the installed-app management surface — and it registers ahead of the/apps/:nameroute, so an app by that name would have an unreachable page).namemust not beregistry,registries,blob,install, orregister; 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 codereserved_app_nameat every install door.namemust 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.versionmust start withMAJOR.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, andbackend.entryPointmust 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.mcpServersentries usecommand/args/url/env. They are not path-checked at manifest load; at registration, whencommandis a barepython,python3orpy, a relative.pylaunch target is resolved against the app root when it is a file inside it (see "An app's own.pylauncher" above). - All required fields must be non-empty strings
config_keysmust be an array of at most 200 non-empty strings, each at most 200 characters long- Each cron entry must specify either
everyorcron_expr - A non-empty
cronsrequires"cron": trueunderpermissions. 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
routeandlabel - Each UI overlay must have
idandreplaces; both must be kebab-case, andidmust be unique within the manifest - Each
platform.osentry must be exactlymacos,linuxorwindows. Spelling and case matter:Windows,winandwindowsmatch no platform, so the platform gate would answer no for the platform the manifest names. The platform stringsdarwinandwin32are refused too platform.installModemust be exactlyserverorclient; the install gates test forclientalone, so a spelling such asClientwould install as a server app
{
"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"]
}
}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.