Publishing & guidelines

Once your app works locally, publish it to the App Store registry so other Crew users can install it with one click. This page covers the workflow end to end.

Create an app directory with an app.json at the root. Refer to:

• Build your first app — the 5-minute walkthrough
• Manifest reference — every app.json field

Verify the manifest validates:

kirocrew doctor
# or:
curl http://localhost:5476/api/apps/my-app/manifest | python3 -m json.tool

# Build UI if you have one
cd my-app/ui && npm install && npm run build && cd ..

# Install via REST API
curl -X POST http://localhost:5476/api/apps/install \
  -H 'Content-Type: application/json' \
  -d '{"source": "./my-app"}'

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

Or use the App Store UI in the dashboard to install from a local path.

1. Open Crew dashboard (kirocrew token → open the URL)
2. Check App Store → Installed — your app should appear
3. If it has UI, click the sidebar entry and verify the page loads
4. If it has agents, test them from chat: ask the agent to do something
5. If it has crons, check the Schedule page — your cron should be listed

# Check the app is registered
curl http://localhost:5476/api/apps | python3 -m json.tool

# Check the manifest is valid
curl http://localhost:5476/api/apps/my-app/manifest | python3 -m json.tool

# Tail gateway logs
kirocrew logs -f

# Edit code
vim ui/src/App.tsx

# Rebuild UI
cd ui && npm run build && cd ..

# Update the installed app
curl -X POST http://localhost:5476/api/apps/my-app/update

For faster iteration, use kirocrew app dev my-app — the gateway hot-reloads the app on file changes.

Before submitting to the registry:

• app.json passes validation
• name is kebab-case, globally unique, descriptive
• version follows semver (1.0.0)
• displayName and description are clear and concise
• author is set
• tags help with discovery
• permissions are minimal — only declare what you actually use
• UI bundle is built and committed (ui/dist/index.mjs)
• Agent JSON files are valid
• Skill SKILL.md files have proper frontmatter
• README.md explains what the app does and how to use it
• If you have setup.onInstall, test it on a clean machine

When Crew installs or updates your app, it copies the source tree into ~/.kiro/crew/apps/{name}/ with two safeguards:

• Symlinks are never followed. A symlink whose target resolves inside your app source tree is preserved as a symlink; a symlink resolving outside is omitted entirely. Committed runtime artifacts must be real files (or in-tree relative links).
• Build-input and VCS directories are excluded: node_modules, .git, __pycache__, .venv (at any depth) are dropped from the installed copy.

Serve your UI from the committed ui/dist/ bundle. Nothing your app needs at runtime may live under those excluded names.

Your app should live in its own git repo (or a subdirectory of an existing repo):

MyAppRepo/
├── app.json
├── agents/
├── skills/
├── ui/
│   ├── src/
│   └── dist/index.mjs        ← committed build artifact
├── scripts/
│   └── install.sh             ← optional; invoked by setup.onInstall in app.json
└── README.md

App icon:

• Format: PNG with transparency
• Size: minimum 256×256, square aspect ratio
• Location: commit to your repo (e.g. assets/icon/logo.png)

Screenshots:

• Format: PNG or JPG
• Recommended: 1200px wide, 16:9 aspect
• Location: commit to your repo
• Max 5 screenshots per app

Hero images (16:9 recommended, 1200×675):

• heroImage — light theme
• heroImageDark — dark theme
• heroImageDetail / heroImageDetailDark — detail-page banner (25:6, 1200×288)

The App Store serves icons and images via a git blob proxy — no CDN or external hosting needed.

The App Registry is src/kiro_crew/apps/app-registry.json in the Crew repo. Adding your app means opening a pull request.

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

If your app is in a subdirectory of a larger repo:

{
  "name": "my-app",
  "gitUrl": "https://github.com/yourname/monorepo",
  "branch": "main",
  "subdirectory": "apps/my-app"
}

The repo field is the legacy shorthand for gitUrl and is still accepted.

The registry entry is intentionally minimal — your app.json is the single source of truth. All display info (description, screenshots, highlights, tags, version) is fetched from your repo. You don't sync metadata between your repo and the registry.

cd /path/to/Crew
git checkout -b add-my-app
# Edit src/kiro_crew/apps/app-registry.json
git add src/kiro_crew/apps/app-registry.json
git commit -m "feat(apps): add my-app to registry"
git push origin add-my-app
# Open a PR titled "Add my-app to App Store registry"

1. app.json is valid and complete
2. Permissions are reasonable (no unnecessary access)
3. No path traversal in resource paths
4. Install script (if any) is safe
5. The app provides value to Crew users

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

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

The registry entry file at the root of the registry repo mirrors the format above (an array of app entries).

Trust model: user explicitly opts in by adding the registry to their config. The repo must be accessible via git.

Management API (/api/apps/registries):

Input validation: repo and branch names are validated against strict regex patterns to reject path traversal. The Crew repo itself is blocked.

After your PR merges:

1. Users open the App Store → Browse tab, find your app
2. Click Install — Crew clones your repo (shallow, specific branch)
3. Runs setup.onInstall if defined
4. Copies the app to ~/.kiro/crew/apps/my-app/
5. Registers agents, skills, crons via symlinks
6. The app appears in the dashboard

Push an update:

1. Update your app code
2. Bump version in app.json
3. Commit and push

Users can update via the App Store UI (refresh button) or REST API:

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

This re-clones, re-runs onUpdate, and re-registers resources.

Some apps manage their own installation and resource registration. They register with Crew for App Store visibility but handle their own lifecycle.

{
  "name": "my-desktop-app",
  "repo": "MyDesktopApp",
  "branch": "mainline",
  "resources": "app",
  "lifecycle": "app",
  "detectInstalled": "test -d ~/Applications/MyDesktopApp.app"
}

Self-managed apps:

• Show in the App Store as "Self-managed"
• Handle their own install / update / uninstall
• Register via POST /api/apps/register at runtime
• Crew only tracks metadata

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 telling the user to update Crew first.

Apps can use npm (for TypeScript/React) or pip (for Python) as their build system. The App Store clones the repo and runs the appropriate build command.

1. Crew creates a workspace at ~/.kiro/crew/app-sources/{name}/
2. Clones the package at the specified branch (shallow)
3. Runs npm install && npm run build (JS/TS) or pip install . (Python)
4. setup.onInstall runs after build (for post-build steps like electron-builder)

Because the standard build step handles dependency resolution and compilation, your onInstall script should only do post-build packaging:

#!/usr/bin/env bash
set -euo pipefail
[ -d "node_modules" ] || exit 1  # sanity check — build should have run

npx electron-builder --mac --dir
cp -R release/mac-arm64/MyApp.app ~/Applications/MyApp.app

• Use semver: major.minor.patch
• Bump patch for bug fixes
• Bump minor for new features
• Bump major for breaking changes (agent config schema, MCP tool interface)

The registry entry has no version field — just bump app.json and push. The App Store fetches the latest app.json from your repo (cached 24h, or immediately on user refresh).

• Questions: file a discussion on the Crew GitHub repo
• Bugs: file a GitHub issue
• Feature requests: same, label app-store