Référence du manifeste

Le manifeste de l'application (app.json) déclare l'identité, les ressources et les exigences de votre application. Il se trouve à la racine du dépôt — ou dans un sous-répertoire si l'entrée du registre en spécifie un.

L'illustration héros s'affiche sur les lignes de liste Discover, la mise en vedette, les cartes de fonctionnalités et la bannière de la page de détails.

Ordre de résolution sur chaque surface : illustration du thème actuel → celle du thème opposé → première capture d'écran → dégradé déterministe avec l'icône de l'application. L'absence d'image héros est gérée proprement.

La forme du chemin dépend de la distribution :

• Applications intégrées — URL absolue servie sous /apps/{name}/ui/
• Applications fédérées / de registre — relative au dépôt (ui/hero-light.svg); le registre la réécrit en URL de proxy blob

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

Les backends d'application sont accessibles via le proxy inverse de la gateway à /apps/{name}/api/{path}, ce qui évite les problèmes CORS pour les pages UI du tableau de bord.

Au lieu d'un processus backend autonome (ou en complément), enregistrez des points d'entrée Python qui s'exécutent à l'intérieur du processus de la gateway :

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

Les hooks sont branchés à l'activation de l'application (via on_app_enable, également réexécuté au démarrage de la gateway) — aucun redémarrage de la gateway n'est requis.

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

Les scripts s'exécutent avec set -euo pipefail imposé par Crew. Les variables non définies et les échecs de pipe entraînent une sortie immédiate — aucune erreur silencieuse.

Limites de délai d'expiration : onInstall / onUpdate = 300 s, onUninstall = 120 s, onEnable / onDisable = configurable (30 s par défaut).

Si onEnable échoue, l'activation est annulée — l'application reste désactivée et toute ressource enregistrée est désenregistrée. Les échecs de onDisable sont consignés comme avertissements mais ne bloquent pas la désactivation.

onUninstall reçoit KEEP_DATA=1 ou KEEP_DATA=0 dans l'environnement — si l'utilisateur a choisi « Conserver les données de l'application », le script doit éviter de supprimer les répertoires de données utilisateur.

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

Les dépendances sont suivies dans un registre à comptage de références. À la désinstallation, Crew indique quelles dépendances peuvent être supprimées en toute sécurité par rapport à celles partagées avec d'autres applications.

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

Lorsque installMode: "client", l'App Store affiche des instructions de terminal à copier-coller au lieu d'exécuter l'installation sur le serveur. À utiliser pour les applications qui doivent s'exécuter sur la machine locale de l'utilisateur (p. ex. les applications Electron lorsque Crew s'exécute sur un hôte distant).

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

Pour les applications qui s'exécutent hors du tableau de bord, openCommand déclare comment les lancer. POST /api/apps/{name}/open l'exécute en arrière-plan. Dans un environnement distant sans interface, le point de terminaison retourne plutôt la commande à exécuter localement.

Appliquées au moment de l'installation :

• name doit correspondre à /^[a-z0-9]+(?:-[a-z0-9]+)*$/ (kebab-case)
• version doit correspondre au format semver (X.Y.Z)
• Les chemins dans agents, skills, sops, ui.entry, ui.pages[].entryPoint, backend.entryPoint doivent être relatifs et rester à l'intérieur de la racine de l'application (les chemins absolus et la traversée .. sont rejetés via une résolution canonique et une vérification de confinement)
• backend.hooks.* sont vérifiés au niveau du format (module.path:callable, aucune traversée exprimable) et vérifiés en confinement au chargement
• Les entrées mcpServers utilisent command / args / url / env — et non des chemins de fichiers relatifs à l'application — et ne sont pas vérifiées quant au chemin
• Tous les champs requis doivent être des chaînes non vides
• Chaque entrée cron doit spécifier soit every, soit cron_expr
• Chaque page UI doit avoir un route et un label

Les champs inconnus dans app.json sont préservés lors de l'analyse et retransmis intégralement via to_dict() / to_json(). Les nouvelles fonctionnalités du manifeste peuvent coexister avec des versions plus anciennes de Crew sans compromettre la 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"]
  }
}