The full path an app takes: develop, test locally, list it in a registry, users install it. An "app" is a package that contributes agents, skills, SOPs, MCP servers, cron jobs, backend routes, or dashboard UI pages to Kiro Crew.
This guide covers the publish-facing surface (store listing, assets, registry entry, review). The complete field reference is manifest-reference.md, and the first-app walkthrough is getting-started.md.
Scaffold a skeleton, then edit it:
kirocrew app init my-app --ui --backend --cronapp.json at the app root is the single source of truth for identity,
resources, and the store listing. The registry entry (section 10) carries almost
nothing, so bumping a version or rewriting a description means editing only your
own repo.
{
"name": "my-app",
"version": "1.0.0",
"displayName": "My App",
"description": "One paragraph describing what the app does.",
"author": "your-name",
"license": "MIT",
"tags": ["productivity", "automation"],
"highlights": [
"What the app does that a list entry cannot convey",
"One line per capability"
],
"iconPath": "assets/icon.png",
"screenshots": ["assets/screenshots/main.png"],
"heroImage": "assets/hero-light.png",
"heroImageDark": "assets/hero-dark.png",
"heroImageDetail": "assets/hero-detail-light.png",
"heroImageDetailDark": "assets/hero-detail-dark.png"
}| Field | Rules |
|---|---|
name |
Required. Kebab-case, matched against ^[a-z0-9]+(?:-[a-z0-9]+)*$, unique across all apps. This is the install id and the on-disk directory name. system is reserved (it would shadow the system.* notification-channel namespace), as are library (the dashboard serves /apps/library as a static page), registry, registries, blob, install and register (shared /api/apps/<name> routes registered ahead of the per-app catch-all), and the Windows device stems con, prn, aux, nul, com1–com9 and lpt1–lpt9 (the name becomes a directory, and Windows resolves those inside every directory). Names that merely resemble one — console, com10, null-app — are fine. All are refused on every platform, so an app that installs on Linux also installs on Windows. |
version |
Required. Semver (major.minor.patch, optionally with a pre-release or build suffix). Bump on every release. |
displayName |
Required. Rendered in a fixed-width row that truncates, so keep it short. |
description |
Required. Plain text, no markdown. Discover's list row shows one truncated line; the feature cards clamp to two; the detail page shows it in full. Two or three sentences is the useful range. |
author |
Recommended. Shown as provenance next to the app's category and source registry. |
license |
Optional SPDX-style identifier, shown on the detail page. |
tags |
Lowercase discovery tags. They also decide the app's Discover category (section 3). |
highlights |
Feature bullets rendered as a list on the detail page. |
The App Store fetches each listed app's app.json with git archive and caches
it for 24 hours (an external registry's index is cached for 1 hour). Image paths
inside the manifest are rewritten to blob-proxy URLs, so nothing has to be
mirrored into the Kiro Crew repo. Push a new version and the store picks it up on
the next refresh.
Once the store sees a version newer than the one installed, Kiro Crew tells the
user itself: a bell notification naming your app and the new version, once per
version, plus the pending-updates count on Discover. Your app can also read the
same answer and show its own banner through useAppInfo().update (see
Getting started).
Two things follow for you. A version bump is user-visible even when nobody opens
the store, so a release published by accident is noticed; and only version
decides it, so re-pushing the same version with different content tells nobody
anything.
Discover groups apps into a fixed set of categories by scanning tags in
priority order, so a specific tag beats a generic one. An app whose tags match
nothing lands in Other.
| Category | Tags that select it |
|---|---|
| On-call & Ops | oncall, operations, monitoring, tickets, pipelines |
| Research & Writing | research, writing, docs |
| Designer Tools | ux, critique, usability, heuristic-evaluation, designer-tools |
| Developer Tools | developer-tools, code-review, git, github, dev, worktrees, pods, issue-triage, code-quality, open-source, performance |
| Agents & Automation | agents, automation, workflows, orchestration, autonomy, autonudge, execution, collaboration, visualization |
| Productivity | productivity, tasks, inbox, slack, email, outlook, files, explorer, aggregation, reports, team |
All artwork is committed to your own repo. The App Store serves it through the
git blob proxy (GET /api/apps/blob?repo=<repo>&path=<path>), so there is no CDN
or external hosting to arrange. The proxy only serves repos that appear in a
configured registry (an SSRF guard), only these extensions: .png, .jpg,
.jpeg, .gif, .webp, .svg, .ico, and it rejects .., absolute paths,
and any path segment starting with a dot.
Path form depends on distribution: a registry app uses a repo-relative path
(rewritten to a blob-proxy URL), while a built-in uses an absolute served URL.
Write every path relative to the directory app.json lives in — for a registry
entry with a subdirectory, the store joins that prefix before it builds the
blob URL, so ui/icons/app.png is fetched as apps/<name>/ui/icons/app.png.
| Field | Rendered where | Aspect |
|---|---|---|
iconPath / iconPathDark |
Card and row icon, the sidebar glyph, and the gradient fallback's centerpiece | Square, 512x512, opaque — no transparency. The dark variant is optional |
screenshots / screenshotsDark |
Detail-page gallery with a lightbox; the first screenshot is also the last-resort hero | Landscape; around 1200px wide |
heroImage / heroImageDark |
Discover rows, Library rows, the featured spotlight, feature cards, and the detail banner when no detail-specific art exists | 16:9 (for example 1200x675) |
heroImageDetail / heroImageDetailDark |
Detail-page banner only, preferred there over heroImage |
25:6 (for example 1200x288) |
The required icon must be opaque. An opaque tile carries its own
background, so it reads correctly on any surface — which is what makes
iconPathDark genuinely optional rather than a latent bug. A transparent icon
that looks right on light chrome turns into a dark smear on dark chrome, and an
app that then omits the dark variant ships a broken card.
Built-in first-party apps take a different path: their icon is an SVG under
/app-assets/, inlined and painted from the theme's --ico-a / --ico-b
tokens, so a single file covers both appearances and no dark variant exists.
Raster art cannot repaint, which is the whole reason the variant field is here.
Ship hero art. Every store surface uses it, and it is the difference between looking like a product and looking like a list entry.
Resolution order on every surface: the current theme's art, then the opposite theme's, then the first screenshot. If an app ships none, or an image 404s, the surface falls back to a name-seeded gradient carrying the app icon, so a missing or broken hero degrades instead of leaving a blank panel. The detail page sizes its container to whichever ratio it resolved, so a 16:9 hero used as a banner is not cropped.
Commit store art as plain bytes, not Git LFS pointers. The pre-install store-art fetch (the owner-tier prewarm that renders icons and screenshots before an app is installed) checks the repository out into a throwaway directory with the operator's global and system git config masked, so no filter driver -- Git LFS included -- can run a program on the operator's machine while reading untrusted art. An LFS-tracked icon or screenshot therefore arrives at the prewarm as its pointer file, which is not an image, and is recorded as unobtainable (the card falls back to the name-seeded gradient). Keep art as plain committed files under the size caps: an art file over 8 MiB is never served, so its card falls back to the gradient, and an owner-tier row prewarms only the first 12 paths of each screenshots field. This limitation applies only to pre-install store art: the install and update paths are not masked and check out LFS content as usual.
{
"setup": {
"onInstall": "bash setup.sh",
"onUninstall": "bash scripts/uninstall.sh",
"onEnable": "bash enable.sh",
"onDisable": "bash disable.sh",
"onEnableTimeout": 120,
"onDisableTimeout": 60
}
}| Hook | When it runs | Timeout |
|---|---|---|
onInstall |
After a registry install has cloned and built the source, before the files are copied into the data home | 300s |
onUninstall |
Before app files are removed, and only after cron cleanup has succeeded | 120s |
onEnable |
After resources are registered, the backend is started, and dependencies are resolved | 30s, or onEnableTimeout (1-300) |
onDisable |
First step of disable, before hooks, backend stop, and deregistration | 30s, or onDisableTimeout (1-300) |
Execution model:
- Every script is wrapped as
/bin/bash -c "set -euo pipefail\n<script>", so an unset variable or any failing command in a pipeline aborts the script. Write scripts assuming bash, and preferbash script.shoversource script.shso the intent is explicit. Native Windows hosts without/bin/bashreport the lifecycle hook as failed; avoid these hooks or document that prerequisite for an app that claims Windows support. - Scripts run sandboxed with a minimal environment (no gateway secrets) plus
NONINTERACTIVE=1, withcwdset to the app directory, under a cgroup ceiling, in their own process group so a timeout kills the whole tree. They must exit 0 on success. Output is truncated to the last lines and passed through credential redaction before it reaches the client. onUninstalladditionally receivesKEEP_DATAandPURGE_DATA(1/0). If the user chose to keep app data, skip deleting user data directories.onEnablefailure rolls the enable back: the backend is stopped, resources are deregistered, and the app stays disabled. Rationale: an app that cannot start should not be left enabled and broken.onDisablefailure does not block the disable. It is reported in the response'swarningsand logged. A misbehaving app must always be disableable; orphaned processes beyond what the backend stop handles are the app's own responsibility.- Installing from a local path (
POST /api/apps/install,kirocrew app install <dir>) copies and registers the app but does not runonInstall. Do any build step yourself while iterating locally. setup.onUpdateparses and round-trips through the manifest, but no code path executes it. Do not put work an update depends on there. MakeonInstallidempotent instead, since a registry update re-runs it.
Only declare onUninstall for state Kiro Crew cannot see: app binaries outside
the data home, shell aliases, launchd plists. For resources: "gateway" apps the
gateway already deregisters agents, skills, MCP entries, and cron jobs, so do not
duplicate that. For resources: "app" apps the gateway deregisters nothing and
your script owns all of it.
{
"dependencies": {
"managedBy": "gateway",
"capabilities": {
"mcp": ["some-documentation-mcp-server", { "id": "my-mcp", "managedBy": "app" }],
"skills": ["SomeSkillPackage"]
},
"commands": ["node", "python3"],
"optionalCommands": ["git"]
}
}| Field | Description |
|---|---|
managedBy |
Default resolution strategy. "gateway" resolves each entry through the edition's CapabilityManager seam; "app" means Kiro Crew only checks existence. A per-entry object ({"id": ..., "managedBy": ...}) overrides it. |
capabilities.mcp / capabilities.skills |
Capability packages the app needs but does not provide. |
capabilities.agents |
Declarable, but no edition has an install operation for it, so it is always reported unresolved. Declare managedBy: "app" or install it out of band. |
commands |
REQUIRED host executables, probed with which. A miss is reported in missing and warned about; it does not block the install. |
optionalCommands |
Same probe, reported separately in missingOptional. Use it for a tool the app can work without or can provision itself. |
The open-source edition ships no capability manager, so capabilities
entries resolve as unresolved and the app installs anyway. Design for graceful
degradation: an app that hard-requires a capability package will not work on a
stock install.
dependencies.capabilities.mcp is not mcpServers. mcpServers are servers
your app itself provides and runs, and the gateway registers them into
Kiro Crew's own agent config. capabilities.mcp are external servers your app
merely consumes.
Resolved dependencies are recorded in a reference-counting ledger at
~/.kiro/crew/dependency-ledger.json. On uninstall each declared dependency is
classified as removable (this app is its only recorded owner), shared (another
app also owns it), or user-installed (absent from the ledger). Only removable
entries are cleaned, and the uninstall request can override that:
keep_dependencies: true skips cleanup entirely, keep_specific: [...] spares
named entries.
{
"platform": {
"os": ["macos"],
"installMode": "client",
"clientInstall": {
"shell": "git clone https://github.com/you/MyApp.git ~/MyApp && cd ~/MyApp && KIROCREW_HOST={{gateway_host}} bash setup.sh",
"postInstall": "open ~/Applications/MyApp.app"
},
"requiresDesktopApp": false
}
}| Field | Default | Description |
|---|---|---|
os |
["macos", "linux"] |
Platforms the app can run on: macos, linux, windows. This constrains the machine the GATEWAY runs on. |
arch |
any | Architecture restriction; empty means any. |
installMode |
"server" |
"server": Kiro Crew clones and installs. "client": the app must be installed on the user's own machine. |
clientInstall.shell |
One-liner the user runs in their local terminal. {{gateway_url}} and {{gateway_host}} are substituted with the dashboard origin and the gateway hostname. |
|
clientInstall.postInstall |
Follow-up command shown as a hint (for example, launching the app). | |
requiresDesktopApp |
false |
The app's UI needs the Electron shell (native always-on-top windows, global shortcuts, tray). A UX gate only: the browser marker is client-side and spoofable, so nothing security-relevant may depend on it. |
With installMode: "client" on an incompatible platform, the store shows the
copy-paste instruction panel instead of running an install, and the app is
registered on first launch via POST /api/apps/register, which requires the
dashboard owner's identity (see section 12, "Self-managed install"). On a compatible
platform the normal clone-and-install path runs.
An installMode: "client" app's onEnable script is treated as advisory: it
launches a desktop application distributed separately, which may legitimately not be
installed on this host. A failure is reported as onEnable.failed and the app stays
enabled, and the script is skipped outright when the gateway's OS is not in the app's
platform.os. Rolling the enable back instead would make the app's dashboard half
unreachable on exactly the hosts that need it to explain how to get the desktop half.
# Build the UI bundle if the app has one
cd my-app/ui && npm install && npm run build && cd ..
kirocrew app install /absolute/path/to/my-app
kirocrew app enable my-appenable refuses an app that is not built in until it is trusted. Enabling it
from the App Store asks you to trust that app alone (agent.apps_trusted);
Settings → Security → Third-party apps lists and revokes those grants, and holds
the switch that trusts every third-party app (agent.apps_allow_third_party). See
Third-party executable code is off by default.
The REST routes require dashboard or app authentication; a bare curl request
is not an equivalent local-install command.
The dashboard's Sources menu on the Apps page can install from a local path too.
Verify:
- Open the dashboard (
kirocrew token, then the printed URL). - Library tab: the app is listed with the right badges.
- If it ships UI, open its sidebar entry and confirm the page loads.
- If it ships agents, ask one to do something from chat.
- If it ships crons, confirm they appear on the Schedule page.
Debug the installed record with kirocrew app info my-app; the install command
reports manifest validation errors directly and names the offending field.
To iterate, rebuild the UI and use the installed app's Update action in the
authenticated App Store UI. The update REST route is available to authenticated
clients, but not to a bare curl request.
For a tighter loop, turn on dev mode (kirocrew app dev my-app, or POST /api/apps/my-app/dev): UI files are then served with Cache-Control: no-store
and a gateway-side watcher broadcasts a reload event when anything under ui/
changes. Agent and skill edits take effect on the next agent invocation with no
rebuild.
Install and update copy the source tree into ~/.kiro/crew/apps/{name}/ with two
safeguards:
- Symlinks are never followed. A symlink resolving inside your app source tree is preserved as a symlink; one resolving outside is omitted entirely. Committed runtime artifacts must be real files (or in-tree links), never reachable only through an external symlink. Absolute in-tree links are rewritten to relative form so the installed copy does not depend on your source directory.
- Build-input and VCS directories are excluded at any depth:
node_modules,.git,__pycache__,.venv, and the gateway's own.kirocrew-depsprovisioning output (plus its transient staging/prior siblings). Serve your UI from a committedui/dist/bundle; nothing needed at runtime may live under those names.
data/ is preserved across updates and, by default, across uninstall.
Code shipped inside the Kiro Crew package (a built-in app) is exempt, but every
other app's executable surfaces refuse to run unless the operator turns
third-party execution on in Settings → Security → Third-party apps ("Trust every
third-party app"), which sets
agent.apps_allow_third_party to the JSON boolean true. That covers registry
installs and their install scripts, detectInstalled, backend processes,
in-gateway Python hooks, lifecycle scripts, and openCommand. Only the literal
true admits: absence, a malformed value, and an unreadable config all deny, and
the env is not consulted, so an app cannot widen the boundary from its own
process.
Point users at that surface rather than at config.json. Turning the setting off
has to STOP the code it was admitting, and the dashboard endpoint behind Settings
is what sequences that — it stops each app while trust still stands, so
on_shutdown hooks can run, and it reports anything it could not stop. A file
edit gets the same revocation, but only once the liveness watch notices, and an
app's shutdown hook can no longer load by then. See
docs/architecture/app-platform-trust-model.md for the full contract.
Non-executable resources (agents, skills, MCP server declarations, cron
definitions, UI bundles) are unaffected. If your app needs any executable
surface, say so in your README: a user who has not turned the setting on will see
app_execution_denied rather than a working install.
Repository layout:
MyAppRepo/
├── app.json
├── agents/
├── skills/
├── ui/
│ ├── src/
│ └── dist/index.mjs <- committed build artifact
├── README.md
└── setup.sh <- optional, referenced by setup.onInstall
Where your app's code lives. Every app reaches people through a registry, never by being added to the Kiro Crew package: Kiro Crew accepts no new built-in app. Every app, first-party included, lives in a dedicated GitHub repository listed in the official registry (kirodotdev/KiroCrewApps), and the official catalog row below is what lists it; the catalog repository holds listing data, never app code. The built-in apps that still ship inside the package are being moved out the same way, so do not copy one of them as a pattern for where a new app goes (decision).
There are two listing surfaces, and they take different paths:
The official App Store catalog is the store's inventory, and it is
maintainer-curated. Its authoring repository is
kirodotdev/KiroCrewApps, which is
public to read and not publicly writable: you can read
catalog/official-registry.json to see the authored shape your entry will take,
but outside authors do not open the listing pull request themselves — there is no
self-serve PR path for third-party apps. A published entry is what
makes your app appear in the store and installable, with no Kiro Crew
release involved: a maintainer authors a git source (URL + a branch or tag;
the publish pipeline resolves and pins the exact commit) plus a category against
the authored schema, and the pipeline emits the published document that clients
read. The authored-vs-published two-schema contract is unchanged — you supply
the source and category, the pipeline pins the commit and bakes version from
your app.json into the published entry. Clients install the pinned commit
exactly and read update availability from the published entry's version field,
so republishing a revised entry is also how an update reaches users.
To request a listing, open an App Store listing request issue using the listing request template. Provide the git source, the ref to pin, the display name, a summary, the category/tags, and author credit, and confirm the section 14 review checklist. A maintainer picks it up and authors the catalog entry with full author credit. (Opening the catalog repository up to outside contributors is a possible alternative, but it is a maintainer-only org-visibility decision, not something an author can do.)
The bundled seed (src/kiro_crew/apps/app-registry.json in the Kiro Crew
repo) is the catalog's offline snapshot, not the listing surface: it is what a
client falls back to when the catalog host is unreachable. Entries here ride the
Kiro Crew release train: a seed change follows the normal contribution flow and
ships with the next release. A catalog row for the same repository supersedes the
seed row, so the seed needs touching only when offline availability matters.
The seed (and any federated registry index) uses this row shape:
[
{
"name": "my-app",
"gitUrl": "https://github.com/yourname/my-app",
"branch": "main"
}
]| Field | Required | Description |
|---|---|---|
name |
yes | Must match app.json's name. |
gitUrl |
yes | Any git-cloneable URL (https://github.com/..., git@host:...). The legacy repo field is still read and used as the clone target when no gitUrl is present. |
repo |
Repo identifier the blob proxy uses to serve committed images. | |
branch |
Branch to read and clone. Defaults to main. For an entry cloning the registry repo itself (the monorepo layout), the registry's configured branch overrides this declaration — the index was read from that branch, so a divergent declaration names a state that does not exist there; the divergence is warning-logged. Entries cloning a different repository keep their declared branch. |
|
subdirectory |
Path within the repo holding app.json, for a monorepo layout. Treated as untrusted: it is joined with symlink-resolving containment and rejected if it escapes the clone root. The store also joins it into every art path the manifest declares (iconPath, heroImage*, screenshots*) when it builds blob-proxy URLs, so those paths stay relative to the app directory. |
|
resources |
"gateway" (default) or "app": who registers agents, skills, MCP servers, and crons. |
|
lifecycle |
"gateway" (default), "app", or "locked": who owns updates and uninstall. |
|
detectInstalled |
Shell command that exits 0 when the app is already present on the machine (for self-managed apps). It runs in the strict sandbox with a 5s timeout and a credential-free environment: only location hints (HOME, PATH, USER, LOGNAME, SHELL, TERM, TMPDIR, locale, and their Windows equivalents) plus git prompt and config suppression. Toolchain variables and git/SSH identity are absent, and stderr is discarded. It runs through /bin/sh, so on native Windows it is not run: the app reads not installed and the gateway logs a warning naming the platform. |
|
featured |
Curator flag for the Discover editorial layer. true marks the app featured; a number both marks it and orders the slots (lower first). It lives on the registry entry, not in app.json, and is honored only for core-registry entries: a featured flag from an external registry is ignored, so adding a registry cannot seize the spotlight. With nothing flagged, the store falls back to a deterministic pick (apps with hero art first, then verified publishers, then name). |
A team can host its own registry without Kiro Crew review per app. Users opt in by adding it to their config:
{
"registries": [
{ "name": "my-team", "repo": "https://github.com/my-team/AppRegistry", "branch": "main" }
]
}The index is read as app-registry.json at the repo root, falling back to
discovering apps/*/app.json when no index file exists. Repo and branch values
are validated against strict patterns, and unsafe subdirectory values are
dropped from the index. Manage registries with GET/PUT /api/apps/registries
(the PUT blocks adding the Kiro Crew repo itself) and POST /api/apps/registries/refresh.
Trust model: the user explicitly opts in by adding the registry, and the repo must be git-accessible.
Credential posture. Apps listed in an external index are cloned
credential-free by default: an anonymous environment plus a strict sandbox that
hides ~/.ssh. This is a confused-deputy defense, because an index the owner did
not author could otherwise point at a private sibling repo on the owner's own
trusted forge and have the gateway read it with ambient credentials.
The same-repo carve-out relaxes that for the monorepo layout. When an index entry's effective clone URL is byte-identical to the registry repo URL the owner configured, the owner did designate exactly that URL, so all three clone chokepoints use owner credentials: the manifest fetch, the install clone, and the App Store's icon/screenshot blob fetch. The comparison is exact string equality with no normalization: sibling repos on the same host stay anonymous and strict.
Private-forge recipe. On a credential-only forge (SSH keys, no anonymous read), keep every app inside the registry repo so the carve-out applies:
app-registry.json # or rely on apps/*/ auto-discovery
apps/
my-tool/app.json
other-app/app.json
With this layout the store lists, installs, and renders icons/screenshots for
those apps using the owner's credentials. Apps in separate repos on the same
private forge do not benefit from the carve-out: under the default index tier
they fail to clone, and their icons and screenshots fall back to the name-seeded
gradient.
Owner-tier registries lift that for the multi-repo layout too. A registry is
owner-tier when the build pins it with trust: "owner", or when the operator
grants it in the dashboard, which records the configured row's repository in the
keystone registry_trust.json. The tier never comes from config.json. When
such a registry's index is fetched fresh, the store fetches
each listed app's app.json and declared images once with the owner's
credentials and caches them where the icon/screenshot proxy reads, so the apps
render fully before install. Only the fresh index drives this — never a cached
row — and nothing from the clone runs.
Owner-tier art needs an unambiguous repo key across ALL your registries.
The prewarm clones an owner-tier row with owner credentials only when exactly one
configured source could be claiming that repo key — the same single-owner rule
the icon/screenshot proxy enforces, so cached bytes can never be served to a
request that reaches the same key through a different registry. It reads this from
each OTHER registry's on-disk index cache, and it fails closed: a sibling
registry whose index cache is absent or unreadable — one that has not fetched
yet on a fresh gateway, or whose cache the periodic GC has reclaimed — counts as a
possible claimant of every key, so until that sibling fetches, every owner-tier
row is treated as ambiguous and left cold (its card shows the name-seeded gradient
rather than its real art). Operators see one store art prewarm: skipping <app> (repo key provenance ambiguous across configured sources) warning per skipped row.
The art warms itself on the next fresh index run once every configured registry
has a readable cache; if it stays cold, check that each sibling registry is
reachable and refreshing (POST /api/apps/registries/refresh) rather than failing
to fetch.
Keep the configured URL byte-identical. Because the carve-out is exact
string equality, editing the registry repo between otherwise-equivalent forms
— ssh://host/x versus ssh://user@host/x, or adding/removing a trailing
.git — silently drops every app back to anonymous + strict. On a credential-only
forge that means apps stop cloning and icons go blank, and the changed URL also
triggers a one-time move-aside re-clone of any already-installed app. This is
deliberate and safe (the new string is a URL the owner did not previously
designate), but if you see "apps stopped cloning after I changed the registry
URL", restore the byte-identical value or expect the one-time re-clone to settle.
The store's Install button (POST /api/apps/registry/install, or the SSE variant
/registry/install-stream that streams the log live):
- Fetch
app.jsonwithgit archiveand check it against the fleet admission policy, so a banned, non-allowlisted, or unsigned app is never cloned. - Check
platform, and answer with client-install instructions instead if the gateway's OS cannot run it. - Check
minKiroCrewVersion. - Clone into
~/.kiro/crew/app-sources/{name}/(persistent, one workspace per app; 60s timeout) and run a detected build:npm installplusnpm run buildwhenpackage.jsondeclares a build script, orpip install ./pip install -r requirements.txtfor a Python source tree. A missingnpmis a logged skip, and so is a gateway interpreter with nopipmodule; when pip is present the step runs on the gateway's own interpreter and a failed run fails the install. An official-catalog entry does not clone a branch: it fetches exactly the commit the published catalog pins and hard-fails on any mismatch, never reuses a pre-existing checkout (the old one is set aside and restored if the install fails), and clones credential-free. On the desktop app the bundled interpreter cannot be installed into, so this step refuses a Python build, except for therequirements.txtwaiver described under "The one desktop exception" in the manifest reference (backend.hookssection). - Run
setup.onInstall(300s). On the desktop app a final desktop-gate pass then re-checks the checkout as the script left it, and a refusal fails the install. - Resolve declared dependencies.
- For a gateway-managed app: copy into
~/.kiro/crew/apps/{name}/, register resources, and start the backend. Forresources: "app": pre-register from the cloned manifest so the app appears immediately, and let the app finish its own registration on next launch.
Requirements: the repo must be git-accessible, app.json must sit at the repo
root or at subdirectory, and the install script must be non-interactive and
finish inside its timeout.
An app with its own installer (an Electron build, a native binary) is registered
at runtime with POST /api/apps/register. The call requires the dashboard
owner's identity: an app token or any non-owner subject gets 403 owner_only.
POST /api/apps/register
{
"name": "my-app",
"version": "1.0.0",
"displayName": "My App",
"manifest": { ...full app.json... },
"resources": "app",
"lifecycle": "app"
}
The call is idempotent: registering again with a newer version updates the entry.
resources and lifecycle default to app when omitted; the gateway always
records origin as external and ignores any origin in the body. Use this when the app has its own build or package system, needs
runtime-dynamic agent configuration, or manages its own agent, skill, and MCP
registration. See
../system-specs/modules/app-kit-platform.md
for what each classification value changes.
Bump version in app.json and push. A seed or federated-registry entry
carries no version, so there is nothing to update there. An official-catalog
entry is different: the published document pins a commit and bakes version
from your app.json at publish time, so pushing to your branch changes nothing
for users — an update ships when the catalog republishes your entry with a new
pin, and clients detect it by comparing the published version against the
installed one.
- Patch for fixes, minor for features, major for breaking changes (agent config schema, MCP tool interface).
minKiroCrewVersionis checked on install and update; too-old gateways get a clear error telling the user to update Kiro Crew first.- Users update from the store or via
POST /api/apps/{name}/update. For a registry-sourced app the update runs its preflight, stops the backend and deregisters the app's resources, then re-clones, rebuilds, and re-runsonInstall. If that install fails, the old version is restored: an enabled app is re-registered and restarted, while a disabled app stays stopped and unregistered.
-
app.jsonvalidates: kebab-casename, semverversion, all required fields non-empty - No
..or absolute paths inagents,skills,sops,ui.entry,ui.pages[].entryPoint,backend.entryPoint -
permissionsare minimal, and each one is actually used - Icon committed, square, opaque, and 512x512
- At least one screenshot and one hero image committed
-
descriptionis plain text and reads well truncated to two lines -
tagsare lowercase and land the app in the right category - UI bundle built and committed (
ui/dist/index.mjs) - Agent JSON files are valid; skill
SKILL.mdfiles have proper frontmatter - Install script is non-interactive, idempotent, and exits 0 within 300s
-
onUninstallcleans up everything created outside~/.kiro/crew/apps/{name}/, and nothing the gateway already manages -
README.mdexplains what the app does and how to use it - The app installs and enables cleanly from a local clone
Reviewers check that the manifest is complete, the permissions are proportionate, resource paths do not traverse, any install script is safe to run, and the app is useful to Kiro Crew users.
| Stage | Command or action |
|---|---|
| Scaffold | kirocrew app init my-app |
| Build UI | cd ui && npm run build |
| Install locally | POST /api/apps/install, or kirocrew app install <dir> |
| Enable | Trust the app first, then POST /api/apps/{name}/enable, or kirocrew app enable <name> |
| Live reload | kirocrew app dev <name> |
| Update local copy | POST /api/apps/{name}/update |
| List a registry app | Official catalog: open an App Store listing request issue (maintainer-curated). Bundled seed or a federated registry: add an entry to app-registry.json, open a pull request |
| User install | Apps page, Discover, Install |
| Ship an update | Bump version, push |
Bugs and feature requests: GitHub issues.