Manifest reference

The app manifest (app.json) declares your app's identity, resources, and requirements. It lives at the repo root — or under a subdirectory if the registry entry specifies one.

Hero art is rendered on Discover list rows, featured spotlight, feature cards, and the detail-page banner.

Resolution order on every surface: current theme's art → opposite theme's → first screenshot → deterministic gradient with app icon. A missing hero degrades cleanly.

Path form depends on distribution:

• Builtin apps — absolute served URL under /apps/{name}/ui/
• Federated / registry apps — repo-relative (ui/hero-light.svg); the registry rewrites it to a blob-proxy URL

{
  "crons": [
    {
      "name": "ticket-refresh",
      "every": 300,
      "message": "Check for new high-severity tickets"
    },
    {
      "name": "daily-digest",
      "cron_expr": "0 9 * * 1-5",
      "message": "Generate daily digest",
      "agent": "digest-agent"
    }
  ]
}

{
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [
      {
        "route": "/apps/my-app",
        "label": "My App",
        "icon": "Shield",
        "entryPoint": "dist/page.mjs",
        "mountFunction": "mount"
      }
    ],
    "sidebar": {
      "section": "Apps",
      "order": 10
    }
  }
}

{
  "backend": {
    "entryPoint": "backend/server.py",
    "port": "auto",
    "healthCheck": "/health",
    "routes": "/api/apps/oncall-watchtower"
  }
}

App backends are accessible through the gateway's reverse proxy at /apps/{name}/api/{path}, which avoids CORS issues for dashboard UI pages.

Instead of (or alongside) a standalone backend process, register Python entry points that run inside the gateway process:

{
  "backend": {
    "hooks": {
      "routes": "backend.routes:register_routes",
      "on_startup": "backend.hooks:on_startup",
      "on_shutdown": "backend.hooks:on_shutdown"
    }
  }
}

Hooks are wired up on app enable (via on_app_enable, also re-run on gateway startup) — no gateway restart needed.

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

Use contributes when your app adds a row or compact control to a Crew-owned surface rather than a page of its own.

Each entry creates a row in the Cmd+K Command Bar. Activating it opens a new chat seeded with prompt; set autoSend only when the command also declares an argument that the prompt interpolates with {argument}.

{
  "contributes": {
    "commands": [
      {
        "id": "summarize-url",
        "title": "Summarize URL",
        "subtitle": "Start a research chat",
        "icon": "FileSearch",
        "keywords": ["research", "summary"],
        "prompt": "Summarize {argument} for this project.",
        "autoSend": true,
        "argument": {
          "kind": "url",
          "placeholder": "https://example.com",
          "hint": "Enter a public URL",
          "hosts": ["example.com"]
        }
      }
    ]
  }
}

Required command fields are id, title, and prompt. subtitle, icon, keywords, and autoSend are optional. An optional argument has kind ("text" or "url"), plus optional placeholder, hint, hosts, and patternError. hosts is valid only for a URL argument. The host validates the declaration; app code does not run inside the Command Bar.

An app can put up to two live controls beside the agent and project chips in the composer. Each is a lazily loaded ESM module and receives the active session identity from the dashboard.

{
  "contributes": {
    "sessionControls": [
      {
        "id": "environment",
        "entryPoint": "dist/session-control.mjs",
        "label": "Environment",
        "icon": "Server",
        "statusPath": "session-status"
      }
    ]
  }
}

id and entryPoint are required. label, icon, and statusPath are optional. When present, statusPath is an app-local backend route; the dashboard calls it with the current session identity and expects { "state": "ok" | "warn" | "none", "tooltip": "..." }.

{
  "setup": {
    "onInstall": "cd ui && npm install && npm run build",
    "onUninstall": "echo cleanup done",
    "onUpdate": "cd ui && npm install && npm run build",
    "onEnable": "echo enabled",
    "onDisable": "echo disabled",
    "configSchema": {}
  }
}

Scripts run with set -euo pipefail enforced by Crew. Unset variables and pipe failures cause immediate exit — no silent errors.

Timeout limits: onInstall / onUpdate = 300s, onUninstall = 120s, onEnable / onDisable = configurable (default 30s).

If onEnable fails, the enable is rolled back — the app stays disabled and any registered resources are deregistered. onDisable failures are logged as warnings but do not block the disable.

onUninstall receives KEEP_DATA=1 or KEEP_DATA=0 in the environment — if the user chose "Keep app data", the script should skip deleting user data directories.

{
  "dependencies": {
    "managedBy": "gateway",
    "capabilities": {
      "mcp": [
        { "id": "some-mcp-server", "source": "registry" }
      ],
      "skills": [
        { "id": "some-skill", "source": "registry" }
      ]
    },
    "commands": ["jq", "node", "python3"]
  }
}

Dependencies are tracked in a reference-counting ledger. On uninstall, Crew shows which deps can be safely removed vs. which are shared with other apps.

{
  "platform": {
    "os": ["macos", "linux"],
    "arch": [],
    "installMode": "server",
    "clientInstall": {
      "shell": "curl -fsSL https://example.com/install.sh | bash",
      "postInstall": "open ~/Applications/MyApp.app"
    }
  }
}

When installMode: "client", the App Store shows copy-paste terminal instructions instead of running the install on the server. Use for apps that must run on the user's local machine (e.g. Electron apps when Crew runs on a remote host).

{
  "openCommand": "open ~/Applications/MyApp.app"
}

For apps that run outside the dashboard, the openCommand declares how to launch them. POST /api/apps/{name}/open runs it in the background. On a headless remote environment, the endpoint returns the command for you to run locally instead.

Enforced at install time:

• name must match /^[a-z0-9]+(?:-[a-z0-9]+)*$/ (kebab-case)
• version must match semver (X.Y.Z)
• Paths in agents, skills, sops, ui.entry, ui.pages[].entryPoint, backend.entryPoint must be relative and stay inside the app root (absolute paths and .. traversal are rejected via canonical resolve + containment)
• backend.hooks.* are format-checked (module.path:callable, no traversal expressible) and containment-checked at load time
• mcpServers entries use command / args / url / env — not app-relative file paths — and are not path-checked
• All required fields must be non-empty strings
• Each cron entry must specify either every or cron_expr
• Each UI page must have route and label

Unknown fields in app.json are preserved during parsing and round-tripped through to_dict() / to_json(). Newer manifest features can coexist with older Crew versions without breaking validation.

{
  "name": "oncall-watchtower",
  "version": "1.0.0",
  "displayName": "Oncall Watchtower",
  "description": "Monitor tickets, pipelines, and alarms for your on-call rotation",
  "author": "kirocrew",
  "tags": ["oncall", "monitoring"],
  "agents": ["agents/ticket-analyst.json"],
  "skills": ["skills/oncall-runbook"],
  "crons": [
    {
      "name": "ticket-refresh",
      "every": 300,
      "message": "Check for new high-severity tickets"
    }
  ],
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [
      {
        "route": "/apps/oncall-watchtower",
        "label": "Oncall",
        "icon": "Shield"
      }
    ]
  },
  "permissions": {
    "api": ["/api/crons", "/api/status"],
    "events": ["notification"]
  },
  "platform": {
    "os": ["macos", "linux"]
  }
}