"Build, package, and publish Kiro Crew external apps. Covers app.json manifests, UI components, crons, skills, lifecycle hooks, development mode, registry publishing, and common pitfalls."
Install
npx skillscat add kirodotdev/kirocrew/kirocrew-app-dev Install via the SkillsCat registry.
Kiro Crew App Development
Guide for building external Kiro Crew apps against the current App Kit manifest, lifecycle, UI SDK, and registry contracts. The canonical field and API references live in App Kit.
When to Use
- User says "create a kirocrew app", "build an app", "make an app for kirocrew"
- User says "package this as an app", "publish this to the app store"
- User is building UI pages, crons, or skills that should be distributable
App Structure
my-app/
├── app.json # Manifest (required)
├── ui/
│ ├── index.mjs # ESM React component (default export)
│ └── icon.svg # Sidebar icon (SVG or PNG)
├── skills/
│ └── my-skill/
│ └── SKILL.md # Skill spec
├── scripts/
│ ├── install.sh # Optional registry-install setup hook
│ └── uninstall.sh # Cleanup script
└── README.md # Optional docsapp.json Manifest
{
"name": "my-app",
"displayName": "My App",
"version": "1.0.0",
"description": "What it does in one sentence.",
"author": "login",
"tags": ["relevant", "tags"],
"skills": [
"skills/my-skill"
],
"crons": [
{
"name": "my-cron",
"message": "Run the scheduled app workflow.",
"every": 900,
"silent": true,
"persistent_session": false
},
{
"name": "market-open",
"message": "Summarise the overnight tape.",
"cron_expr": "30 9 * * 1-5",
"timezone": "America/New_York",
"skip_dates": ["2026-12-25"]
}
],
"permissions": {
"api": ["/api/apps/my-app/config", "/api/chat", "/api/chat/*"],
"mcpTools": ["local_knowledge_search", "send_message"],
"network": true,
"cron": true
},
"ui": {
"entry": "index.mjs",
"pages": [
{
"route": "/apps/my-app",
"label": "My App",
"iconUrl": "icon.svg"
}
]
},
"setup": {
"onInstall": "bash scripts/install.sh",
"onUninstall": "bash scripts/uninstall.sh"
}
}Critical Rules
| Field | Rule | Why |
|---|---|---|
skills |
Prefer canonical string paths ["skills/my-skill"] |
Legacy object entries with path or name are normalized by AppManifest.from_dict, but the public manifest schema is string[] |
permissions |
Must be an object; supported grants are api, events, mcpTools, storage, network, memory, cron, sessionApproval, spawn, jobs, and exposeToApps |
A non-object parses to empty permissions, and malformed capability grants fail closed |
resources |
Omit from app.json; declare app resources with agents, skills, sops, and mcpServers |
resources is install/registry ownership metadata ("gateway" or "app"), not an app-manifest resource array |
ui.entry |
Use an ESM .mjs bundle; .js is also served |
HTML is not in the app UI static-file allowlist |
ui.pages[].iconUrl |
Use an app-relative image path for a custom icon | ui.pages[].icon also works for supported host Lucide names and falls back to Package |
ui.loading.layout |
Optional: "page" (default), "rail", "centered" or "split", e.g. "loading": { "layout": "rail" }. Pick the one closest to your first paint |
The dashboard shows nothing for 300 ms, then this placeholder shape until the bundle mounts. It is a closed set the host draws; no custom markup or CSS. Anything else, including "Rail", falls back to "page" |
displayName |
Required | Gateway uses it for UI display |
version |
Semver string | Used by the App Store registry to compute updateAvailable |
crons[].timezone |
IANA zone name; omit it only when the hour is zone-agnostic | An empty timezone falls back to the gateway config's zone and then to UTC, so "cron_expr": "0 6 * * *" without it fires at 06:00 UTC — the wrong calendar day for most users. A per-USER zone is not manifest data: pass timezone= to ctx.cron.add_job instead |
crons[].skip_dates |
Zero-padded YYYY-MM-DD, evaluated in timezone |
"2026-1-1" parses but never matches the padded fire-time rendering, so the skip silently does nothing. Both fields are rejected at manifest validation, not at fire time |
crons[].timeout / crons[].timeout_secs |
Set both on a script cron that runs longer than 30s, e.g. "timeout": 60, "timeout_secs": 65 |
Omitted, a script is killed at 30s and a command at 300s. timeout_secs must cover timeout plus 5s of cleanup; a pair the cron SDK would refuse is rejected at manifest validation |
Lifecycle and Resource Registration (CRITICAL)
Do not make a cron mutate the installed app tree or create skill links. When an
app is enabled, the gateway registers its declared agents, skills, SOPs, MCP
servers, and crons; gateway startup reconciles enabled app resources again.
Lifecycle scripts have explicit scope:
- A local-path
kirocrew app install <dir>copies the app but intentionally does
not runsetup.onInstall; build the local source before installing it. - A registry install runs
setup.onInstallin the cloned source before copying
it into the data home. Keep that hook idempotent. setup.onEnable/onDisablerun around enablement, andonUninstallis only
for external state Kiro Crew cannot remove itself.
Keep runtime data under the app's data/ directory. The gateway owns registered
resource links and scheduler entries; app code must not recreate them manually.
UI Development
Design System
Kiro Crew apps should default to the host visual language. Colors come
from the theme tokens (var(--accent) and friends) — see "Don't Reinvent the
Dashboard" below, which is the normative rule. The hex values here are the legacy
palette, kept for apps that predate the tokens and as the fallback insidevar(--accent, #7c3aed); a hardcoded hex breaks every custom palette, so reach for
one only when a deliberate custom style is the point.
| Element | Style |
|---|---|
| Styling method | Prefer @kirocrew/app-sdk/ui components and theme tokens; CSS, host utility classes, or inline styles are all valid. |
| Primary accent | var(--accent) (legacy: #7c3aed) |
| Light accent bg | legacy #e8d5f5 |
| Success color | #047857 (green) |
| Warning color | #b45309 (amber) |
| Danger color | #b91c1c (red) |
| Buttons | borderRadius: '9999px' (full pill), font 11px weight 500 |
| Badges | borderRadius: '9999px', 10px bold, colored bg+text |
| Cards | background: 'var(--bg)', border: '1px solid var(--border)', borderRadius: '6px', padding: '14px' |
| Max width | maxWidth: '1200px' |
| Font sizes | 10px (version/badges), 11px (body/buttons), 12px (table), 13px (section headers), 18px (title) |
| Theme vars | var(--bg), var(--text), var(--muted), var(--border), var(--card) |
Example badge:
_jsx('span', {
style: { background: '#e8d5f5', color: '#7c3aed', padding: '2px 7px', borderRadius: '9999px', fontSize: '10px', fontWeight: 600, letterSpacing: '0.02em' },
children: 'LABEL'
})Example primary button:
_jsx('button', {
style: { background: '#7c3aed', color: '#fff', border: 'none', padding: '5px 14px', borderRadius: '9999px', fontSize: '11px', fontWeight: 500, cursor: 'pointer' },
children: 'Action'
})Example secondary/ghost button:
_jsx('button', {
style: { background: 'transparent', color: '#7c3aed', border: '1px solid #e8d5f5', padding: '5px 14px', borderRadius: '9999px', fontSize: '11px', fontWeight: 500, cursor: 'pointer', whiteSpace: 'nowrap' },
children: '↻ Refresh'
})Reference Implementation
For a working example, use docs/app-kit/examples/, which contains installable
external-app patterns. Builtins under src/kiro_crew/apps/builtins/ are useful
for UI idioms, but their backend and lifecycle contracts differ from external
apps.
Visual mock of the target style:
<!--
Legacy geometry reference for a Kiro Crew app header and card.
Use host components and theme tokens instead of copying the hardcoded colors.
-->
<div style="max-width:1200px; margin:0 auto; padding:16px; font-family:system-ui; color:#e2e8f0; background:#1a1b26">
<!-- Header -->
<div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:16px">
<div style="display:flex; align-items:center; gap:10px">
<span style="font-size:18px; font-weight:600">Review Tender</span>
<span style="background:#e8d5f5; color:#7c3aed; padding:2px 8px; border-radius:9999px; font-size:10px; font-weight:600">Every 15 min</span>
</div>
<div style="display:flex; align-items:center; gap:10px">
<span style="font-size:11px; color:#6b7280">Last scan: 3m ago</span>
<button style="background:transparent; color:#7c3aed; border:1px solid #e8d5f5; padding:5px 14px; border-radius:9999px; font-size:11px; font-weight:500">↻ Refresh</button>
<span style="font-size:10px; color:#6b7280">v1.7.0</span>
</div>
</div>
<!-- Card -->
<div style="background:#1a1b26; border:1px solid #2d2f3d; border-radius:6px; padding:14px; margin-bottom:12px">
<div style="font-size:13px; font-weight:600; color:#7c3aed; margin-bottom:8px">Open Reviews Being Tended (2)</div>
<!-- Table row example -->
<div style="display:flex; align-items:center; gap:8px; padding:6px 0; border-bottom:1px solid #2d2f3d; font-size:12px">
<a style="color:#7c3aed; text-decoration:none">#1234</a>
<span style="font-size:11px; max-width:180px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap">Fix manifest dict format</span>
<span style="background:#fef3c7; color:#b45309; padding:2px 7px; border-radius:9999px; font-size:10px; font-weight:600">iterating</span>
<span style="margin-left:auto">
<button style="background:transparent; color:#7c3aed; border:1px solid #e8d5f5; padding:5px 14px; border-radius:9999px; font-size:11px; font-weight:500">💬 Chat</button>
</span>
</div>
</div>
<!-- Update banner -->
<div style="background:#e8d5f5; color:#7c3aed; padding:8px 14px; border-radius:9999px; font-size:12px; display:flex; justify-content:space-between; align-items:center">
<span>Update available: v1.6.0 → v1.7.0</span>
<button style="background:#7c3aed; color:#fff; border:none; padding:5px 14px; border-radius:9999px; font-size:11px; font-weight:500">Update Now</button>
</div>
</div>Key visual rules from the mock:
- Dark theme uses
var(--bg)/var(--border)/var(--text)— don't hardcode dark hex - Light purple badge for metadata (
#e8d5f5bg,#7c3aedtext) - Amber status pills (
#fef3c7bg,#b45309text) - Ghost buttons with purple text on light purple border
- Version as plain muted text (smallest element, 10px)
- Cards have 14px padding, 6px radius, 12px bottom margin
Entry Module Pattern
import { useState, useEffect } from 'react'
import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from 'react/jsx-runtime'
import { useAppApi, useAppInfo, useNavigate } from '@kirocrew/app-sdk'
export default function MyApp() {
const [state, setState] = useState({})
const [loading, setLoading] = useState(true)
const api = useAppApi()
const { version: appVersion } = useAppInfo()
const navigate = useNavigate()
useEffect(() => {
async function load() {
try {
setState(await api.get('/api/apps/MY-APP/config'))
} finally {
setLoading(false)
}
}
load()
const interval = setInterval(load, 30000) // 30s polling
return () => clearInterval(interval)
}, [api])
// ... render UI
}Version Source (IMPORTANT)
Read the installed manifest version from useAppInfo(). The host mounts external
apps inside AppApiProvider and supplies {name, version, permissions, active};
apps are not iframes and do not need to derive absolute data-home paths.
const { version: appVersion } = useAppInfo()Do not cache a version in data/config.json, hardcode a user-specific install
path, or bypass the scoped SDK with /api/file-read just to read app.json.
Header Layout Pattern
All apps use a consistent header: Icon + Title + badge on the left, last-scan + refresh + version on the right.
_jsxs('div', {
style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '16px' },
children: [
_jsxs('div', { style: { display: 'flex', alignItems: 'center', gap: '10px' }, children: [
// Inline SVG icon (same as ui/icon.svg, rendered at 20px with purple stroke)
_jsx('svg', { xmlns: 'http://www.w3.org/2000/svg', width: 20, height: 20, viewBox: '0 0 24 24',
fill: 'none', stroke: '#7c3aed', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round',
children: [/* your icon paths */] }),
_jsx('h2', { style: { margin: 0, fontSize: '18px' }, children: 'My App' }),
_jsx('span', { style: { background: '#e8d5f5', color: '#7c3aed', padding: '2px 8px', borderRadius: '9999px', fontSize: '10px', fontWeight: 600 }, children: 'Every 15 min' })
]}),
_jsxs('div', { style: { display: 'flex', alignItems: 'center', gap: '10px' }, children: [
_jsx('span', { style: { fontSize: '11px', color: 'var(--muted)' }, children: lastScan }),
_jsx('button', { /* refresh - see below */ }),
_jsx('button', { /* version pill - see below */ })
]})
]
})Inline icon rules:
- Render the same SVG from
ui/icon.svgdirectly in JSX (20x20px,stroke: '#7c3aed') - Use
_jsx('svg', {...})with child_jsx('path', { d: '...' })elements - Don't fetch the icon file at runtime — inline it for instant render
Background Actions (MANDATORY)
All buttons that trigger agent work MUST run in the background through the permission-scoped useAppApi() client and POST /api/chat?ws=1. NEVER navigate to /chat for automated actions — the user should stay on the app page.
// Refresh button (background)
_jsx('button', {
disabled: refreshing,
onClick: async () => {
setRefreshing(true)
await api.post('/api/chat?ws=1', {
message: 'Run the workflow...',
slot: 'my-app-refresh'
}).catch(() => {})
setTimeout(() => setRefreshing(false), 5000)
},
style: { background: 'transparent', color: refreshing ? 'var(--muted)' : '#7c3aed', border: '1px solid #e8d5f5', padding: '4px 10px', borderRadius: '9999px', fontSize: '11px', fontWeight: 500, cursor: refreshing ? 'default' : 'pointer' },
children: refreshing ? '↻ Running…' : '↻ Refresh'
})
// Version link (host-managed update details)
_jsx('button', {
onClick: () => navigate('/apps/detail/my-app'),
title: 'Open App Store details',
style: { background: 'none', color: 'var(--muted)', border: 'none', padding: '2px 6px', fontSize: '10px', cursor: 'pointer' },
children: `v${appVersion || '?'}`
})Only use navigate('/chat') for actions that genuinely need human involvement (responding to reviewer comments, complex setup wizards).
UI Rules
| Do | Don't |
|---|---|
| Prefer host components and theme tokens | Assume inline styles or Tailwind are mandatory |
Use useAppApi() with an app-owned route or config endpoint |
Bypass the permission-scoped SDK with raw fetch |
Use useNavigate() from @kirocrew/app-sdk for navigation |
Use window.location (causes full reload) |
| Use theme vars for backgrounds/text/borders | Hardcode hex for theme-dependent colors |
Use theme tokens (var(--accent)) for accent elements |
Hardcode #7c3aed outside a var(--accent, …) fallback |
Read version from useAppInfo() |
Read version from data/config.json or derive an absolute install path |
Run background work through useAppApi().post('/api/chat?ws=1', ...) |
Navigate to /chat for automated actions |
| Show a loading/error state when config is unavailable | Show cryptic error messages |
Read app state through an app-owned API or /api/apps/MY-APP/config |
Derive arbitrary absolute data-home paths in UI code |
When app UI moves, or draws a live figure such as a gauge or a diagram, theliving-ui skill's rules apply to it too. An app may bundle that skill's
toolkit, toolkit/living-ui.js, instead of inlining its helper blocks. The file
exports nothing, so end the app's copy with export { LivingUI }; and import it.
Available Gateway APIs
| Endpoint | Method | Returns |
|---|---|---|
/api/apps/MY-APP |
GET | Full manifest JSON through authenticated, permission-scoped app access |
/api/apps/MY-APP/config |
GET/PUT | App-owned JSON config; declare it in permissions.api |
/api/project/tree |
GET | Active-project tree when declared in permissions.api |
/api/chat?ws=1 |
POST | Launches agent work in background slot |
/api/file-watch |
GET (SSE) | Live file change stream (avoid — see above) |
/api/project/tree lists the active project when the app declares that API
permission. For an app-owned data directory, keep a bounded _index.json instead
of asking for arbitrary filesystem traversal.
Available Imports (via shared import map)
react(useState, useEffect, useRef, etc.)react/jsx-runtime(_jsx, _jsxs, Fragment)react-dom@kirocrew/app-sdk— hooks (useAppApi,useAppEvents,useTheme,useAppInfo,useNavigate,useNotify,useNavBadge,useChatLauncher,useChatSession), theChatEmbed/ChatPanel/ChatMessageListcomponents, the transcript's row
registry (defaultMessageRenderers,mergeRenderers,resolveRenderer,ToolCallPill), and the chat marker protocol (parseOptions,deriveFollowUpOptions,extractSteeringAcks,stripPartialOptionMarker). The protocol
is React-free, so a worker or a plain function can use it too. The registry is how you add
a transcript row type or replace one instead of hand-rolling a message list — seedocs/app-kit/api-reference.md.
Interactive Elements (Chat Launch)
For actions requiring human interaction, use the supported launcher rather than
writing the host's private global directly:
const { openChat } = useChatLauncher()
openChat({ message: 'Your prompt here', autoSend: false })Interactive Widgets (data-action)
For button callbacks within mcwidgets rendered by the agent (not app UI):
<button data-action="approve" data-payload='{"id":"123"}'>Approve</button>User receives: [UI] approve: {"id":"123"}
Cron Design
Notification Deduplication
Never ping the user for the same unchanged condition. Track what was communicated:
"last_notified": {
"event": "new_comment",
"at": "2026-05-19T17:00:00Z",
"details": "soopra: Can you explain..."
}Before sending any DM:
- Check
last_notified.eventandlast_notified.details - If same → SKIP
- If different → SEND and update
last_notified
Silent by Default
Set "silent": true in cron config. Use send_message only for a genuine new development the user needs to act on; do not hardcode session="slack" unless the app is explicitly Slack-only.
Cron Message Structure
Keep the cron prompt focused on the scheduled work. Resource registration and
lifecycle setup belong to the gateway and declared hooks, not shell bootstrap
commands embedded in an agent prompt.
Background work and downstream services
A cron is the one thing your app does to somebody else's service with no user
watching. Get the cadence wrong and the owner of that service sees load from
every install at once, cannot tell which app it is, and fixes it the only way
they can: throttling. That breaks your app, not just its polling.
Declare static crons in the manifest; use CronSDK for dynamic schedules
Put install-wide schedules in the crons array of app.json. The gateway
reconciles that array through register_app_crons_with_service
(src/kiro_crew/apps/bridges_crons.py) at enable and gateway startup. Registration is
add-if-absent under one store lock, keyed by cron name.
A schedule derived from user configuration may instead use ctx.cron / CronSDK;
those jobs remain app-namespaced and are removed by app teardown. Never write the
cron store directly. Declare permissions.cron for either form, and keep dynamic
schedule configuration visible in the app UI and README.
Cadence: a 5-minute floor, push over polling
| Rule | Why |
|---|---|
| Never more often than every 5 minutes when the job calls a third-party or shared service, and never per-minute polling | Every install runs the same schedule, so the service absorbs installs × frequency and has no channel to ask you to slow down |
| Prefer a webhook, changelog, event feed or push subscription wherever the service offers one | A poll asks "did anything change" a thousand times to learn "no". Push tells you once, when it did. register_hook is the callback side of this |
| Poll only where no push path exists, and then at the coarsest cadence the feature tolerates | A stale panel is a smaller cost than an app the service owner has to block |
A 5-minute schedule gets no jitter from the platform, so add your own.compute_jitter (src/kiro_crew/cron_service/schedule.py; cron.py only
aliases it as _compute_jitter) returns 0.0 for a strict_schedule job, a
one-shot at job, every under 3600s, and any cron_expr whose minute field
expands (via croniter) to * or to more than one value, so ranges, lists and
steps all count; only hourly schedules get spread (0 to 5 minutes) and daily
ones (0 to 59).
Nothing spreads a 5-minute job, so anything that makes it overdue on many
machines at once (a released app update, a gateway restart, a fleet coming back
after an outage) fires it immediately on all of them and lands as one
synchronised burst on the service.
So spread it yourself. Pick one stable offset per install, uniform in[0, interval) — hash the install id, or write a random value once into your
state file — and reuse that same number every tick. A fixed offset per install,
not a fresh one per run: a stable offset keeps each install's schedule
predictable while pulling the fleet apart, and survives the restart that would
otherwise re-align everybody. Bounding it below the interval is what stops a
hashed offset from pushing a 5-minute job past its own next tick.
Apply it as a phase offset your own due-check honours: read the offset, and
treat the tick as not-yet-due until now has passed that offset inside the
current window. Sleeping the offset at the top of the tick reaches the same fire
time, but it is the worse form — a multi-minute sleep holds the run's session
open for most of the interval — so keep the sleep for an offset of a few seconds
and use the phase offset for anything longer.
Bounded concurrency
The scheduler will not overlap a job with itself: the due-scan skips any job
that holds a run claim (is_running, src/kiro_crew/cron_service/service/run_registry.py), so a slow run
delays its own next tick rather than doubling up. What is not bounded is what
you do inside one run. There is no per-app cap on sessions or subagents today;
per-app quotas are still a draft phase indocs/request-for-change/rfc-app-sandbox-isolation.md. So a tick that fans out
one agent session per work item is your bug, paid for by the user's machine and
the service you called.
- One in-flight run per cron, and let it finish.
- Fan out over a small fixed batch per tick, not over the whole result set.
- Keep a cursor in your state file so the next tick continues instead of
restarting the sweep.
Backoff and a circuit breaker
- Retry
429and5xxwith exponential backoff, and honourRetry-Afterwhen
the service sends it. Do not retry any other4xx: it will fail identically
forever. - Persist consecutive failures in your state file and stop calling after a
threshold. An in-memory counter is useless here, because each cron run is a
fresh process; only the state file survives to the next tick. - Re-probe an open breaker at most once per interval, and show the tripped state
in the UI so the user knows why the panel is stale.
Identify the app on outbound calls
Send an app-specific User-Agent, or fill in whatever client-name field the API
offers: my-app/1.2.0 (kirocrew-app). Load a service owner cannot attribute is
load they can only throttle wholesale, and an app that is identifiable is one
they can contact instead of block. Where a service has both a public API and a
browser-private one, use the public one.
Tell the user before they click setup
The anti-pattern is a single Setup button that silently installs a per-minute
cron against a shared service. Before any background work starts, the UI must
state:
- what will run, one plain line per cron, not the cron expression
- how often
- which service it calls, and whose credentials it uses
- how to turn it off
Repeat it in the README and the store description. The store card is where most
users actually decide.
Disable and uninstall must stop everything
Disable removes every cron job the app owns (created_by="app:<name>"),
whether or not the manifest declares permissions.cron: _cleanup_app_crons
in src/kiro_crew/apps/hooks_integration.py is keyed off the running cron
service, not the grant (#13788, which closed
issue #10997). When the
cron store is busy or unreadable, disable reports cron_cleanup: failed ...
in its result instead of raising, so read the result rather than assuming.
- Declare
permissions.cronif you ship any cron at all. Install, update and
self-registration refuse a manifest whosecronsis non-empty without it. - Keep
permissionstruthful both ways. Declare what you use, drop what you no
longer use. Grants are read at the gateway boundary, never inferred from your
code, so an over-broad block is a real grant and a missing one is a real
failure. scripts/uninstall.shmust always stop background work and remove anything
the app registered outside its own directory. User state is a separate
decision and is not yours to make. Uninstall preserves app data by default
(keep_data = Trueinsrc/kiro_crew/apps/routes_uninstall.py, flipped only by an
explicitpurge_datarequest), and that choice reaches your script asPURGE_DATA/KEEP_DATAin its environment. So delete state files only
underPURGE_DATA=1, and leave them untouched underKEEP_DATA=1. A script
that deletes unconditionally destroys data the user asked to keep, with no
recovery path.- Verify by hand: disable the app, then confirm none of its jobs remain on the
Schedule page.
Reviewer checklist
- Every schedule lives in
app.jsoncrons; no handler writes to the cron store. - No schedule fires more often than every 5 minutes against a third-party or shared service, and none polls per minute.
- Polling is used only where the service offers no webhook, changelog or push.
- A 5-minute or sub-hourly schedule carries its own per-install offset; the platform adds none. Read it off the diff rather than trusting the box:
app.jsondeclares the sub-hourlyevery, the state file schema holds an offset key, and the tick reads that key before its first outbound call. A schedule under 3600s with no offset in state fails this line. - Each tick has bounded fan-out; no session-per-item.
- Backoff on
429/5xxplus a circuit breaker persisted in state. - Outbound calls carry an app-specific identifier.
- The UI names what runs, how often, and against which service before setup.
-
permissions.crondeclared; disable leaves no jobs; uninstall stops all background work and deletes user state only underPURGE_DATA=1. - Manifest
permissionsmatch what the code actually uses.
Publishing to App Store
1. Git Repository
Publish the app as a plain git repository (any git host — e.g. GitHub):
- Include:
app.json,ui/,skills/,scripts/ - Any git-cloneable URL works (
https://github.com/<org>/<repo>,git@host:...,ssh://...)
2. App Registry Entry
Open a pull request to the Kiro Crew repo adding an entry tosrc/kiro_crew/apps/app-registry.json:
{
"name": "my-app",
"gitUrl": "https://github.com/<org>/my-app",
"branch": "main"
}gitUrl alone resolves. repo is a legacy alias for the same clone URL and is
only read when gitUrl is absent; it is never a slug.
That file is the offline seed. The live App Store reads official-registry.json
from the hosted catalog at https://apps.crew.kiro.dev/, so a listing lands there
too, alongside its editorial and category-order files.
Display metadata (description, tags, author) comes from app.json in the app's own repo (cached 24h).
3. Updates
Bump version in the app repository and publish it. The App Store enriches the
registry row with installedVersion and updateAvailable, then performs updates
through its authenticated Update action (POST /api/apps/{name}/update). From a
terminal, kirocrew app update <name> [--source <dir>] sends the same request to
the running gateway; it has no file-only fallback.
Host-Managed Update Pattern
Do not add an app-owned update-check cron or run git archive --remote against
GitHub. The registry already compares semantic versions and the gateway owns the
clone, admission, lifecycle, rollback, and resource re-registration steps. Link
users to the App Store when an update action is needed.
Self-Update & Refresh Pattern
Use a background slot for app-specific refresh work, but leave app package updates
to the App Store. An agent prompt must not replace the gateway's authenticated
update transaction.
Background Slot Pattern
For any action that should run without navigating away from the app page, use POST /api/chat?ws=1 with a named slot:
api.post('/api/chat?ws=1', {
message: 'Do the thing...',
slot: 'my-app-action-name'
})- The slot is created if it doesn't exist, reused if it does
- Response is JSON
{ok: true}— the work runs async in the background - Results surface via state file changes picked up by the 30s polling cycle
- Use a disabled/spinner state to show feedback while in flight (5-10s timeout)
Installation Flow (User Perspective)
kirocrew app install /path/to/my-appcopies a local directory containingapp.json; a registry install is initiated from the App Store and performs the clone.kirocrew app enable my-appgrants activation and registers declared resources. A normal install/enable does not require a gateway restart.- The enabled app page appears in the sidebar when
ui.pagesis declared. - Manifest crons register with the scheduler; local installs intentionally skip
setup.onInstall, while registry installs run it before copying the app. - Use
kirocrew app dev my-appduring UI iteration instead of restarting the gateway.
.gitignore (IMPORTANT)
Apps generate local install artifacts that must NOT be committed to the repo:
/build
/release-info
.app_secret
app-crons.json
installed.json
data/The data/ directory contains machine-local runtime config and user state. Do not store the app version there; useAppInfo() supplies the installed manifest version.
Git Workflow for Installed Apps
The installed directory under ~/.kiro/crew/apps/ is deployment output, not a
Git workspace: the safe copy deliberately omits .git. Edit and commit in the
source repository, then use the App Store Update/Sync action (or reinstall from
the local source during development). Never commit or push from the installed
copy.
Common Pitfalls
| Pitfall | Cause | Fix |
|---|---|---|
| "no visual interface" in sidebar | Missing ui.entry or wrong extension |
Use .mjs ESM with default export |
| Skills do not load after enable | Declared path is missing/escaping, or the app is still disabled | Use canonical string paths and inspect skill_search; the gateway owns namespaced and flat links |
| UI or manifest changes do not appear | The installed copy is a snapshot of the source | Use App Store Sync/Update, or documented app dev mode for UI changes |
onInstall does not run for a local-path install |
Local installs intentionally skip the registry build hook | Build locally before install; registry installs execute setup.onInstall |
| SSE overwrites React state | /api/file-watch fires immediately on connect |
Use polling instead |
| Cron spams DMs | No dedup — same condition triggers every cycle | Track last_notified in state |
App icon falls back to Package |
Unsupported ui.pages[].icon name or bad iconUrl |
Use a supported host Lucide name or a valid app-relative image path |
| App changes disappear after update | Editing the installed snapshot or a dev symlink that safe-copy replaces | Edit the source, update/sync, and recreate any explicitly granted dev link |
| Version shows "?" or an old number | Version was cached outside the host-provided app context | Read useAppInfo().version |
| Install artifacts in git | data/, .app_secret, etc tracked |
Add to .gitignore, git rm --cached |
| Buttons navigate away from app | Using navigate('/chat') for automated work |
Use permission-scoped useAppApi().post('/api/chat?ws=1', ...) |
| Package update bypasses App Store safeguards | Asking an agent slot to rewrite the installed app | Use the authenticated App Store Update/Sync action |
| Cron keeps firing after the user disables the app | Disable reported cron_cleanup: failed (cron store busy/unreadable) |
Re-run disable, then verify no job remains on the Schedule page |
| Every install hits the same service in the same minute | Sub-hourly schedules get zero jitter, so a rollout or restart syncs them | Add a stable per-install offset in your own state file, or go hourly or coarser and let the platform spread it |
| Downstream service starts throttling the app | Unattributable polling load from every install | A 5-minute floor with no per-minute polling, push/webhook instead of polling, app-specific User-Agent |
| One cron tick spawns dozens of agent sessions | Fan-out per work item, with no per-app quota to stop it | Bounded batch per tick plus a cursor in the state file |
Testing Locally
- Build the app in its source directory.
- Install:
kirocrew app install /path/to/my-app. - Enable:
kirocrew app enable my-app. - Verify the UI, declared cron jobs on the Schedule page, and the namespaced skill through
skill_search. - For UI iteration, enable
kirocrew app dev my-app; no gateway restart is required.
Versioning Convention
- Patch (1.0.x): Bug fixes, wording changes
- Minor (1.x.0): New features, new crons, UI additions
- Major (x.0.0): Breaking changes to state format, removed features
In-Process Backend for External Apps (CRITICAL — differs from builtins)
External (installed) apps CAN ship a Python backend that runs inside the gateway
process — but the contract DIFFERS from builtins (auto_research etc.):
- Manifest: use ONLY
backend.hooks("routes": "backend.routes:register_routes").
Do NOT set thebackend.routesbase-path string — that field triggers the
STANDALONE-PROCESS proxy, which serves dead stubs that shadow your handlers. register_routes(ctx)receives an AppContext and MUST returnlist[AppRoute]
(from kiro_crew.apps.route_registry import AppRoute) with paths RELATIVE to/api/apps/<name>;{params}land inrequest.match_info.- Handlers take
(request, ctx); gateway state isrequest.app["state"];
auth-checkrequest.get("user") is not None→ else 401. - The builtin pattern (direct
app.router.add_get) silently never dispatches for
external apps — the RouteRegistry catch-all (/api/apps/{app_name}/{path:.*})
shadows it. - Backend hook changes need a gateway restart OR an app disable→enable cycle
(runtime deregister + module unload + fresh load). UI files reload without. - Trust: backend code runs UNSANDBOXED with full gateway privileges (SEC-012
warning logged;agent.apps_allow_third_party=falserefuses it entirely).
Dev Loop for App UIs
- Preferred: dev mode —
kirocrew app dev <name>(off:--off). Serves that
app's UI withCache-Control: no-storeand watches itsui/dir; changes
broadcastapp_reloadand the dashboard hot-swaps the app in ~1s. The flag
lives ininstalled.jsonand toggles live. - To edit in your source tree, symlink the installed UI dir to source, then
explicitly grant that out-of-install root:mv ~/.kiro/crew/apps/<n>/ui ~/.kiro/crew/apps/<n>/ui.bak && ln -s <src>/ui ~/.kiro/crew/apps/<n>/ui
followed bykirocrew app dev <n> --confirm-out-of-install-root. That
confirmation is a human security decision; agents must not supply it.
On native Windows use a directory junction instead (PowerShell):Rename-Item "$env:USERPROFILE\.kiro\crew\apps\<n>\ui" ui.bak; New-Item -ItemType Junction -Path "$env:USERPROFILE\.kiro\crew\apps\<n>\ui" -Target "<src>\ui"
(pathlibresolves junctions the same way, so serving and the watcher work;
the lifecycle clobber below applies identically — junctions are also never
preserved by the install/update safe-copy). - ⚠️ Symlinks do NOT survive the app lifecycle.
install_app/update_app
(reinstall, App Store Update, registry refresh) re-copy source over the
installed dir with a DELIBERATE symlink-stripping safe-copy (security: blocksui -> ~/.dockerstyle serving). Your symlink is silently replaced by a
frozen snapshot: hot reload stops, UI goes stale, no error. Symptom:ls -l ~/.kiro/crew/apps/<n>/uishows a real dir, not a link. Fix: re-create
the symlink after ANY install/update, and re-check dev mode is still on. - Same clobber applies to locally edited shipped skills: installed skill files
under~/.kiro/crew/skills/re-sync from the Kiro Crew package on update.
Durable bundled-skill changes belong insrc/kiro_crew/builtin_skills/;
top-levelskills/is checkout-only guidance. - Validate
.mjsbefore relying on a reload:node --check ui/index.mjs—
a parse error surfaces only as "Failed to load : Unexpected token". - Avoid deep
_jsxnesting in one expression; prefer small named components. - Dark mode: never pair a solid light accent bg with hardcoded dark text for
selected states — use a translucent accent tint (e.g.rgba(124,58,237,.14))
withvar(--text)/var(--muted). Self-contained pills (own bg+fg) are fine.
Don't Reinvent the Dashboard (default posture)
By DEFAULT, apps should look and behave like the dashboard they live in:
- Theme tokens over hardcoded colors:
var(--accent),var(--accent-fg),var(--accent-subtle),var(--danger)/var(--danger-subtle),var(--ok),var(--bg)/var(--card)/var(--border)/var(--text)/var(--muted).
Hardcoded hex breaks the moment a user picks a custom palette (and error
banners hardcoded for light mode glow in dark mode). Give tokens fallbacks
(var(--accent, #7c3aed)) so old hosts still render. - Host components over hand-rolled ones: the
@kirocrew/uimodule-map
export shipsBtn, Input, SearchInput, Badge, Toggle, EmptyState, Skeleton, ContentSkeleton, PageHeader, SegmentedControl, MarkdownRendererand more;lucide-reactships a subset of real icons. Feature-detect
(window.__kirocrew_modules?.['@kirocrew/ui']) and keep a small fallback for
old hosts — a thin wrapper per component (host when available, fallback
otherwise) keeps call sites clean.
This is the default, not a straitjacket: if your app has a deliberate,
preferred custom style or a novel interaction with no host equivalent (bespoke
visualizations, a branded look, domain-specific widgets), a custom design is a
legitimate choice — make it consciously and consistently, not as an accident of
copy-pasted inline styles. Custom visuals should still respect the theme's
background/text tokens so they don't break light/dark/custom palettes.
Embedded Chat (ChatEmbed) — native chat inside your app
The host SDK ships the dashboard's real chat renderer. Use it instead of
hand-rolling a transcript view — markdown, tool activity, streaming, and turn
grouping come for free and stay consistent with the main chat.
- Access:
const sdk = window.__kirocrew_modules?.['@kirocrew/app-sdk'], then
rendersdk.ChatEmbedwith{ slotKey, agent?, placeholder? }. Feature-detect
and keep a lightweight fallback — the module map can lag one gateway version. slotKeybinds the embed to a chat slot (<app-name>-<entity>is the
convention). The embed polls/api/chat/slots/<key>(1s while running, 5s
idle) and POSTs to/api/chat.- Manifest permissions (silent-failure trap): the SDK gates fetches by the
app'spermissions.apiallowlist. ChatEmbed needs"/api/chat"and"/api/chat/*"; its Approve/Trust controls use the slot-scoped/api/chat/slots/{slot}/approveroute covered by that wildcard. - Chrome and scroll are props, not CSS overrides. Pass
framelessto drop the
bordered card, title strip and input-row border so the embed sits flush inside
your own card, andstartAtBottomto jump to the newest turn immediately and
stay pinned there (released when the user scrolls up more than 40px, re-pinned
when they return). Do NOT reach for!importantoverrides on the embed's
Tailwind classes or hand-roll a scroll keeper: those couple you to host DOM
internals the repo has never promised. - Permission cards render inside ChatEmbed and route Approve, Reject, and Trust
through the slot-scoped approval endpoint. Keep attended worker slots
interactive instead of granting blanket trust merely to avoid a dead card. - Rendering agent messages yourself instead of using
ChatEmbed? An agent puts
follow-up choices and steer acknowledgements inline in its prose
([OPTIONS: a | b],[STEERING steer-<id>: …]). Parse them with the SDK's
marker protocol rather than by hand, and remember the rule that costs users
their input: stripping a marker WITHOUT offering the affordance deletes the
choices outright — worse than showing the raw text.
Worker Slots — apps that own agent sessions
If your app creates chat slots for background/worker agents (spec writers,
researchers), acquire them through kiro_crew.apps.worker_slots:
from kiro_crew.apps.worker_slots import WorkerSlotTimeout, acquire_worker_slot
try:
async with await acquire_worker_slot(
state, "<app-name>", "<app-name>-<entity>",
project=working_dir,
trusted_patterns=["npm test"], # or trust=True; both expire
trust_ttl_secs=3600, # at most 24h
timeout=30, # seconds to wait for a free slot
) as lease:
... # drive lease.slot
except WorkerSlotTimeout as exc:
... # tell the user the worker is busy; str(exc) says why- Re-stamped on every acquire. The helper sets the slot's app owner (keeps
it out of the main chat sidebar) and its working directory every time, so a
slot another path created first (ChatEmbed's own POST, for one) is fixed on
the next acquire. Acquire again rather than reusing a slot object you kept. - One at a time by default. Each app may hold 1 lease at once, and one
slot key is leased by one lease at a time across all apps. A further acquire
waits up totimeoutseconds, then raisesWorkerSlotTimeoutnaming the
app, the limit and the wait. A slot owned by another app raisesValueError, and so does a chat a person or a cron job opened; pick keys
prefixed with your app name. A lease whose slot was
deleted is freed by the next acquire. Callset_worker_slot_limit("<app-name>", n)once at startup if your app really
runs several workers side by side. The limit lives in the gateway process
and starts fresh after a restart. - Trust is bounded. Attended workers should use ChatEmbed's approval cards
and pass no trust. For an unattended worker prefertrusted_patterns(only
the command shapes it needs) over blankettrust=True. Blanket trust is an
audited, expiring scoped grant, never the session's own trust flag, so
subagents the worker spawns do not inherit it. Either grant is withdrawn
when the lease is released or aftertrust_ttl_secs(default 1h, at most
24h), whichever is first. A grant whose audit cannot be written is not made:
checklease.trust_granted. A grant the slot already had is left alone. - Working directory.
projectbecomes the CLI process cwd, so commands
are relative and readable and the worker inherits project-scoped steering
files.
Do not stamp slot._app, slot._trust, slot._trust_scope,slot._trusted_patterns or slot.project by hand: they are private, and the helper is the supported way.
Positioning — your app is NOT in an iframe
App UIs mount directly into the dashboard DOM. position: fixed therefore
escapes your panel and covers the ENTIRE dashboard (sidebar, header). For
overlays/modals scoped to your app: set position: relative on your app root
and use position: absolute; inset: 0 for the overlay.
Backend Change Ergonomics
- UI hot-swaps in ~1s (dev mode); backend hooks load only on gateway restart or
an app disable→enable cycle. Batch backend edits and plan one reload. - Validation loop:
python3 -m py_compile backend/routes.pythen copy to the
installed dir — it takes effect on the NEXT reload, silently. Track what's
pending. - Verify the served UI module actually updated before debugging "my change
doesn't work":curl -s <gateway>/apps/<name>/ui/index.mjs | md5sumvsmd5sum <src>/ui/index.mjs. A mismatch means clobbered symlink or dev mode
off. - Probe a backend route without auth plumbing: an auth-gated route returning
401/403 proves it is REGISTERED; 404 means the module didn't load.
Graduating an External App to a Builtin
When an app proves out and should ship with Kiro Crew, port it into the repo —
the contracts CHANGE on both sides. Template: src/kiro_crew/apps/builtins/issue_radar/.
- Layout:
src/kiro_crew/apps/builtins/<snake_name>/withapp.json,backend/routes.py, optionalskills/<skill>/SKILL.md,tests/. - Backend contract flips: builtins use
register_routes(app: web.Application) -> None
registering FULL paths (/api/apps/<name>/…) directly on the router — the
external AppRoute-list/RouteRegistry contract does not apply. Wrap every
handler in an enabled-check gate (see issue_radar's_require_enabled):
builtin routes exist at startup even while the app is disabled. - Wiring: in-process builtin backends must be listed in
BUILTIN_NAMES(apps/builtins/__init__.py) — that startup loop is what
callsregister_routes. (Subprocess-backend builtins like dev_fleet usebackend.entryPoint+ port instead and are NOT listed.) App Store discovery
is separate and automatic viadiscover_builtin_apps()scanningapp.json. - UI becomes a real React page:
website/src/apps/<name>/…Page.tsx
registered inwebsite/src/apps/builtinRegistry.ts(lazy import). You now
import MarkdownRenderer, lucide-react, the ui kit, and app-sdk components
directly — delete the module-map feature detection and CSS override hacks.
Note ChatEmbed requires anAppApiProviderancestor; builtin pages mount
their own. - Icon/assets:
website/public/app-assets/<name>/; manifesticonUrl/app-assets/<name>/icon.svg. Skills ridemanifest.skills(paths relative
to the app root), registered at enable-time. - Keep
defaultEnabled: false; users opt in via the App Store. - Full worktree + build-gate discipline applies (see the kirocrew-worktree-dev
skill) — this is now Kiro Crew source. - Tests: the suite under
tests/follows the repo's test rules — the
writing-tests
skill and the
Determinism contract.
The rootdirconftest.pyfloor applies there (plus the app's owntests/conftest.py
where one exists), nottest/conftest.py, and the helpers undertest/are not on
your import path: take shared test support fromkiro_crew.testing, which ships in the package (kiro_crew.testing.clock,.wait,.idsand.links), and the rootdir'smanual_clock,seeded_rngandlocal_tz
fixtures.