Want to add your app curation to the official HexOS catalog? Install scripts now live in the hexos-app-catalog repository — this is the single source of truth for all curated and community install scripts.
myapp.json).ts files in a subdirectory (e.g., myapp/myapp_hook.ts) — or use inline scriptContent for simpler hookshexos-app-catalog/
├── _lib/
│ └── hook_context.ts # HookContext type stubs (import for autocompletion)
├── myapp.json # Your install script (V4 or V5)
├── myapp/ # Hook scripts directory (V5 only, optional)
│ └── myapp_hook.ts # Hook implementation
├── plex.json # Example: first-party V5 with hooks
├── plex/
│ └── plex_hook.ts
├── jellyfin.json # Example: V4 script (no hooks)
└── ...
"version": 4."version": 5 and add a hooks array. See the Hooks Reference for details.Both formats are fully supported. Use V5 only if your app benefits from post-install automation.
scriptContent)Community contributors who don't need separate .ts files can embed hook code directly in the JSON using the scriptContent field. This keeps everything in a single file:
{
"version": 5,
"custom": true,
"metadata": { "name": "My App", "description": "...", "icon": "...", "version": "1.0.0" },
"hooks": [
{
"id": "health-check",
"event": "onAfterInstall",
"scriptContent": "export async function setup(ctx) {\n await ctx.waitForApp('/health');\n await ctx.emitCheckpoint('ready');\n}",
"entrypoint": "setup",
"timeout": 60,
"description": "Post-install health check",
"optional": true
}
]
}
Testing with Custom Install
You can test inline hook scripts using Custom Install in Expert Mode — paste your V5 JSON withscriptContenthooks directly into the editor and run it. This is useful for development and testing before submitting a PR. Inline scripts should not be part of a PR submission for testing purposes only — submit them when they're ready for production use.
optional: true for non-critical automation$LOCATION() macros instead of hardcoded pathsowner on directories that need specific permissionsNot ready for a PR? Share your install script JSON in the HexOS Community Forums to get feedback from other users first.