Apps

The App Kit is what turns Crew into a platform. An app is a package that contributes any combination of agents, skills, MCP servers, cron jobs, dashboard UI pages, or backend processes to Crew. Users install apps from the built-in App Store; developers publish apps by adding an entry to the app registry.

This section covers the app landing here, plus four subpages:

• Build your first app — get an app running in 5 minutes
• Manifest reference — every field in app.json
• SDK / API reference — TypeScript and Python client APIs
• Publishing & guidelines — from development to App Store listing

An app can contribute any subset of these:

An app that only ships skills is one file. An app that ships a full agent + backend + UI can be a whole project.

From the App Store in the dashboard:

1. Browse or search for an app
2. Click Install — Crew clones the repo, runs the app's install script, and copies files to ~/.kiro/crew/apps/{name}/
3. Click Enable — the app registers its resources (agents, skills, crons, MCP servers) and lifecycle hooks fire
4. The app appears in the dashboard sidebar (if it has UI pages)

Via the REST API:

curl -X POST http://localhost:5476/api/apps/install \
  -H 'Content-Type: application/json' \
  -d '{"source": "/path/to/my-app"}'

curl -X POST http://localhost:5476/api/apps/my-app/enable

Via CLI dev mode:

kirocrew app dev my-app         # turn on live-reload for local iteration
kirocrew app dev my-app --off   # turn off

Apps declare who manages their resources and lifecycle:

resources: "gateway" is the default and easiest — write an app.json, Crew reads it and wires everything up. resources: "app" is for self-managed apps (Electron desktop apps, native binaries) that need to control their own installation and register at runtime via POST /api/apps/register.

The App Store is a curated list in src/kiro_crew/apps/app-registry.json. Adding an app means opening a pull request against the Crew repo:

[
  {
    "name": "my-app",
    "gitUrl": "https://github.com/yourname/my-app",
    "branch": "main"
  }
]

Once merged, users can install with one click. See Publishing & guidelines for the full workflow.

Teams can host their own app registries without requiring Crew team review for each app. Users opt in by adding external registries to their config:

{
  "registries": [
    {"name": "team-a", "repo": "TeamAKirocrewAppRegistry", "branch": "main"}
  ]
}

External registries are searched after the built-in registry. Trust model: user explicitly opts in by adding the registry.

Apps with backend processes are accessible through the gateway's reverse proxy at /apps/{name}/api/*. The gateway signs each proxied request with X-Crew-Proxy: <timestamp>:<hmac-sha256> — backends verify this to authenticate the caller as the gateway itself.

This avoids CORS issues for dashboard UI pages and gives apps a stable, gateway-authenticated way to talk to their own backend without minting tokens.

Turn on dev mode for an installed app and the gateway:

• Serves the app's UI files with Cache-Control: no-store
• Watches the app's ui/ directory
• Broadcasts an app_reload WebSocket event on any file change
• The dashboard reloads the app immediately

Recommended local workflow:

# 1. Symlink your source tree into Crew's app directory
ln -sfn /path/to/my-app-src/ui ~/.kiro/crew/apps/my-app/ui

# 2. Turn on dev mode
kirocrew app dev my-app

# 3. Edit → save → dashboard hot-reloads

Turn it off when you're done — dev mode adds file-watching overhead.

Apps declare what they can access in app.json:

{
  "permissions": {
    "api": ["/api/crons", "/api/status"],
    "events": ["notification", "slots"],
    "mcpTools": ["cron_add", "cron_list"],
    "storage": true,
    "cron": true,
    "network": false
  }
}

Apps live in separate git repos. On install, Crew clones the repo (shallow, specific branch) into ~/.kiro/crew/app-sources/{name}/, runs the build step (npm install && npm run build for JS/TS packages, pip install . for Python), then copies the app to ~/.kiro/crew/apps/{name}/.

Symlinks are never followed on copy — a symlink to inside the app source is preserved as a symlink; a symlink to outside is dropped. Build-input and VCS directories (node_modules, .git, __pycache__, .venv) are excluded from the installed copy — commit build artifacts to ui/dist/ if the app needs them at runtime.

Contributes agents and skills. No UI, no backend. Example: an oncall triage agent.

{
  "name": "oncall-triage",
  "agents": ["agents/triage.json"],
  "skills": ["skills/ticket-analysis"]
}

Agents + skills + backend + dashboard UI page. Example: a monitoring dashboard.

{
  "name": "service-monitor",
  "agents": ["agents/monitor.json"],
  "backend": { "entryPoint": "backend/app.py" },
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [{ "route": "/apps/service-monitor", "label": "Monitor", "icon": "Activity" }]
  }
}

External app (Electron, CLI tool, native binary) that registers with Crew at runtime. Example: Mochi desktop pet.

{
  "name": "mochi",
  "resources": "app",
  "lifecycle": "app",
  "platform": { "os": ["macos"], "installMode": "client" }
}

The app calls POST /api/apps/register on startup and manages its own resources.

Apps declare minCrewVersion in app.json. Install and update check this — if the current version is too old, the operation is rejected with a clear error message.