> ## Documentation Index
> Fetch the complete documentation index at: https://kiro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps

> Build and distribute apps that run inside Crew. App Store, manifest-driven install, dashboard UI pages, backends, agents, skills.

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](https://kiro.dev/docs/crew/apps/build-first-app.md) — get an app running in 5 minutes
- [Manifest reference](https://kiro.dev/docs/crew/apps/manifest.md) — every field in `app.json`
- [SDK / API reference](https://kiro.dev/docs/crew/apps/sdk.md) — TypeScript and Python client APIs
- [Publishing & guidelines](https://kiro.dev/docs/crew/apps/publishing.md) — from development to App Store listing

## What apps can do

An app can contribute any subset of these:

| Contribution | Purpose |
|---|---|
| **Agents** | Custom `kiro-cli` agent configs, model, prompt, tool list |
| **Skills** | On-demand or always-on knowledge markdown files |
| **MCP servers** | New tools the LLM can call |
| **Cron jobs** | Scheduled work the app owns |
| **UI pages** | Custom pages rendered in the dashboard sidebar |
| **Backend processes** | HTTP servers reverse-proxied through the gateway |
| **Gateway hooks** | Lifecycle callbacks (`onEnable`, `onDisable`, session start/end) |

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

**ℹ️ Info:** Third-party apps are disabled by default. To allow them to run, enable the toggle under **Settings → Security**.

## Install and enable

### Use the Library Launchpad

Open **Apps → Library** to see installed apps as a Launchpad grid. Each tile has an **Open** button, a pin badge when its page is pinned in the sidebar, and a menu with **Details**, **Update**, **Disable**, and **Uninstall**.

The Library also includes **Create Folders From Project**. Choose a project, select its packages, and Crew creates a nested sidebar folder for each selected package.

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//`
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:

```bash
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:

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

## Two lifecycle modes

Apps declare who manages their resources and lifecycle:

| Mode | Who registers agents / skills / crons / MCP | Who handles install / update / uninstall |
|---|---|---|
| **`resources: "gateway"`, `lifecycle: "gateway"`** (default) | Crew | Crew |
| **`resources: "app"`, `lifecycle: "app"`** | The app | The app |
| **`lifecycle: "locked"`** | Crew | Cannot uninstall (built-in) |

`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

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:

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

Once merged, users can install with one click. See [Publishing & guidelines](https://kiro.dev/docs/crew/apps/publishing.md) for the full workflow.

### Federated external registries

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:

```json
{
  "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.

## Reverse-proxy for app backends

Apps with backend processes are accessible through the gateway's reverse proxy at `/apps//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.

## Dev mode

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:

```bash
# 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.

## Permissions (advisory today)

Apps declare what they can access in `app.json`:

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

**ℹ️ Info:** Today, `permissions.api` **is** enforced (via the app-token scope check — deny-by-default on out-of-scope paths). The other fields (`events`, `mcpTools`, `storage`, `cron`, `network`) are advisory and not yet enforced in-process. Full in-process enforcement is on the roadmap. Design defensively: declare only what you use.

## Federated app model

Apps live in separate git repos. On install, Crew clones the repo (shallow, specific branch) into `~/.kiro/crew/app-sources//`, 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//`.

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.

## App types

### Agent-only app

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

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

### Full-stack app

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

```json
{
  "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" }]
  }
}
```

### Self-managed app

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

```json
{
  "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.

## Version compatibility

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.

## What's next

  - [Build your first app](https://kiro.dev/docs/crew/apps/build-first-app.md) — Get a Crew app running in 5 minutes. Manifest, UI, agent, and install.
  - [Manifest reference](https://kiro.dev/docs/crew/apps/manifest.md) — Every field in app.json — required, recommended, and optional.
  - [SDK / API reference](https://kiro.dev/docs/crew/apps/sdk.md) — TypeScript hooks, Python client, Gateway REST endpoints.
  - [Publishing & guidelines](https://kiro.dev/docs/crew/apps/publishing.md) — From local development to a listed App Store entry.