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
  }
}

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