# Hoody Exec reference **Page:** kit/exec/reference [Download Raw Markdown](./kit/exec/reference.md) --- # Hoody Exec reference Lookup tables for [Hoody Exec](/kit/exec/). Every route, field and response is in the [Hoody Exec API reference](/api/exec/script-execution/). ## Which mode fits | Workload | Mode | Why | |---|---|---| | Instant APIs, internal tools (admin dashboards, data migrations, reports) | Either | Each file is an endpoint as soon as it exists. Worker suits speed with caching; serverless suits sporadic traffic or a fresh context per request. | | Real-time services: WebSocket chat, live dashboards, SSE streams, collaborative tools | Worker | The long-lived context holds connections and `shared` state. Ordinary script WebSockets need persistent connection handling, so only worker mode serves them. | | Session tracking, rate limiting, connection pools | Worker | `shared` persists across requests with zero overhead. | | High request volume, frequently called endpoints | Worker | Later requests reuse the cached context. | | Webhook receivers (Stripe, GitHub, Slack) | Serverless | A fresh context per request resets context-local state; `@concurrent false` processes deliveries one at a time. | | One-off tasks, sporadic traffic, nothing kept in the context | Serverless | Building a context per request costs less than keeping one alive. | | Prototyping | Either | Iterate with magic comments, without a deploy step. | | Hoody AI interception, proxy hooks | Worker | Both are listed as worker workloads; see [Hoody AI Intercept & Control](/foundation/hoody-ai/mitm/) and [Proxy Hooks](/foundation/proxy/hooks/). | - Keep scripts small and focused (under 200 lines), and watch request latency through the [monitoring API](/api/exec/monitoring/). ## Script lookup order | Rule | Detail | |---|---| | Order | `scripts/default//`, then `scripts/default/`, then `scripts//`, then the scripts root (`/hoody/storage/hoody-exec/scripts/`). The first folder with a matching script wins. | | Symbolic links | Regular routes found by scanning are tried first. Explicit-path symbolic links can then be followed before hostname or global index fallbacks. | | `.exclusive` | An empty file named `.exclusive` in the instance folder (for example `scripts/default/1/.exclusive`) turns the fallbacks off for that instance, and stops it running any script reached through a symbolic link. | | `default` | The subdomain folder. Public exec URLs always serve from `default`. | | Extra hostname label | A hostname with a name in front, such as `myapp.{projectId}-{computerId}-exec-1.{server}.computers.hoody.com`, does not reach your computer. | | Exec ID | Lowercase letters and digits only, such as `1`, `test` or `demoapi`. A folder named with a hyphen, underscore or dot (`demo-api`) is still listed but never served. | | Disabled script | A script with `@enabled false` answers `404`, and no other script is tried. | [Routing](/kit/exec/routing/) has dynamic routes, priority and middleware. ## Instance and script lists | Call | Returns | |---|---| | `GET /api/v1/exec/list` | The exec instance IDs in the `default` namespace, each with its source type and a `files` count. For custom instances the count is every file in its directory, `.md` and `.env` files included. | | `GET /api/v1/exec/scripts/list` | The top-level files and folders of the instance's script directory, leaving out symbolic links and never-routed folders such as `node_modules`. Subdirectories are not expanded; with `recursive=true` the list holds the files below instead, with no folder entries. With `exhaustive=true` it lists every entry below the folder with its type. | | Instance type | In the instance list, `type` is `custom` for an instance holding your own scripts and `sdk` for one holding an [imported API](#imported-sdks). The CLI and SDK call exec instances namespaces (`hoody exec namespaces list`). | List one instance's scripts: ```bash # List the scripts of the exec instance hoody exec scripts list -c "$COMPUTER_ID" -o json ``` ```typescript const scripts = await computerClient.exec.scripts.list(); console.log(scripts); ``` ```bash curl "https://$PROJECT_ID-$COMPUTER_ID-exec-1.$SERVER.computers.hoody.com/api/v1/exec/scripts/list" ``` Lists the top level of this instance's script folder; `recursive=true` lists the files below, and `exhaustive=true` every entry with its type. ## Magic comment rules | Rule | Detail | |---|---| | When read | At script load time. They take precedence over defaults, and an edited comment applies to the next request. | | Exception | `@schedule`, `@schedule-timeout` and the `@timeout` a scheduled run falls back to: after editing the file directly, call `POST /api/v1/exec/schedules/reload`. The scripts and magic-comments APIs do this for you. | | Placement | Before any code, imports included, and within the first 30 lines. Directives after line 30 are ignored, except `@return-type` and `@return-type-mode`, which are read anywhere in the file. | | Syntax | A space after `//`. Check the comment name's spelling. | | Syntax errors | A syntax error in the code stops the script from running but does not stop the comments being read. | | Checking | The validation API parses and checks them: `POST /api/v1/exec/validate/magic-comments`. | | `@cors` | Reflective CORS is on by default; use `@cors reflective` during development. `// @cors *` is an alias for it; pin one origin for production with `// @cors https://app.com`. | | Logging | Set a logging level suited to your debugging. | Every comment is on [Magic Comments](/kit/exec/magic-comments/). ## Timeouts | Case | Behaviour | |---|---| | Default | One hour. Raise it with, for example, `// @timeout 2h`, or set `// @timeout 0` for no limit (risky). A lower value set earlier, such as `// @timeout 60000`, is the limit you hit. | | Deadline | A request that has received nothing by the deadline gets `504`. A script that has already started keeps running, and a response already under way, such as a stream, is not cut off. | | Waiting time | The deadline also counts time spent loading the script and waiting for a `@concurrent` slot. A script that has not started by then never runs. | | `pre.ts` exception | When `pre.ts` or `pre.js` already sent headers, left the response open and returned nothing, the main script can still start after the deadline. | | Proxy hooks | A request from a [proxy hook](/foundation/proxy/hooks/) uses the hook's own deadline instead, which can cut off a response already under way. | | Scheduled runs | `@schedule-timeout` if set, otherwise `@timeout`, otherwise 30 seconds. | | Blocking code | Synchronous code that blocks the server for longer than its watchdog limit (30 seconds by default) gets the server restarted, whatever `@timeout` says. | ## Concurrency | Rule | Detail | |---|---| | Default | Unlimited concurrent requests in both modes. A worker handles them in its shared context. | | `@concurrent N` | Caps parallel runs, for example `@concurrent 5` to prevent overload. Past the cap, requests queue. | | `@concurrent false` | Serial processing, for example for webhooks. | | Scope | Applies in worker and serverless mode, to cron fires, and to remote `send` and `call`. Messages to an ordinary script WebSocket are not held back by it. | | Finer control | Manage concurrency yourself with semaphores or queues. | | Watching | Watch request activity through the [monitoring API](/api/exec/monitoring/). | ## Shared state and context | Rule | Detail | |---|---| | Scope | One `shared` object per instance (hostname and exec ID), the same in worker and serverless mode. | | Emptied by | A computer restart, clearing it, or the service evicting that hostname's idle state. Each empties it for new requests. | | Open WebSockets | A WebSocket connection that is still open keeps the old object until it closes. | | Serverless modules | Modules you `require` or import can keep state between requests, so keep delivery-specific data out of them. | | Remote functions | In serverless mode, functions a script registers for [remote](/kit/exec/remote/) messages and calls keep the variables of the run that registered them. | | Worker context | Built by the first request, and again after a restart or cache eviction. | | Old keys | Clean up keys you no longer need so memory does not leak. | [State loss on restart](/kit/exec/execution-modes/#state-loss-on-restart) has worked examples. ## Packages and auto-install | Rule | Detail | |---|---| | Detection | Packages your script names with a plain string in `require()` or `import` are checked and installed with `npm install`. The install status is cached. | | Computed names | A package named by a computed value, such as `require(name)`, is not detected: install it first with the [package management API](/api/exec/package-management/). | | Versions | The latest versions, unless you pin them in a `package.json`. Pin for production stability, test dependencies before deploying, and watch `node_modules` grow. | | Version in the specifier | `require('lodash@4.17.21')` fails with `ERR_VERSIONED_SPECIFIER`; pin it in `package.json` instead. | | Always-available packages | An installed copy older than the version range Hoody Exec lists for one is reinstalled on use. Without a pin that brings the latest version; a version pinned in the scripts folder's `package.json` survives the reinstall, so the older copy stays. A successful reinstall is not repeated until the server restarts. | | `hoody-sdk` | Installed the same way, and kept current: Hoody Exec downloads a newer npm release in the background and switches to it when it restarts, unless the scripts folder's `package.json` declares an exact version or a non-semver specifier such as the `latest` dist-tag. A range keeps updates within that range. Automatic updates stay within the same major version, or the same minor below `1.0.0`, and never move to or from a prerelease. To move further, use `POST /api/v1/exec/dependencies/install`. | | Type checks | `typecheck: true` on the validation endpoints checks types, calls on `hoody` included, against the installed `hoody-sdk`, and `GET /api/v1/exec/sdk-types` looks up exact signatures, so an agent finds a wrong method or argument before deploying. See [Check SDK calls before they run](/kit/exec/writing-scripts/#check-sdk-calls-before-they-run) and [Type-check a script](/kit/exec/writing-scripts/#type-check-a-script). | [Writing Scripts](/kit/exec/writing-scripts/#pre-installed-packages) lists the pre-installed packages. ## Schedules after a restart Schedules run after a computer restart while at least one enabled script has `@schedule`; a script with `@enabled false` does not count. | Case | What happens | |---|---| | With schedules | Hoody Exec normally starts on demand, when something calls it. While it has schedules it keeps a marker file, and Hoody Daemon starts it after a computer restart when that file exists ([boot start with a marker file](/kit/daemons/#boot-start-with-a-marker-file)). | | Without schedules | It stays stopped after a restart until something calls it. | | Missed fires | Fires that fall while Hoody Exec is not running are skipped, not run late. | | Stopped by you | If you stop the `hoody-exec` program yourself, a restart of Hoody Daemon alone does not start it again. | ## Restart `POST /api/v1/exec/system/restart` restarts the Hoody Exec service, not the computer; `GET /api/v1/exec/system/restart-status` follows it. Use it, for example, to switch to a newer `hoody-sdk` it has downloaded. | Field | Default | Effect | |---|---|---| | `graceful` | `true` | Drain in-flight requests before restarting. `false` exits at once. | | `drainTimeoutMs` | `5000` | The longest wait, in milliseconds, for in-flight requests before the restart goes ahead. | | `reason` | `"API restart request"` | Recorded with the restart. | The call answers `202` once the restart is accepted. See [System](/api/exec/monitoring/#system). ## Imported SDKs `POST /api/v1/exec/sdk/import` takes another API's OpenAPI document and an exec ID. Its GET, POST, PUT, DELETE and PATCH operations become proxy script URLs on that instance, forwarding calls with optional `pre` and `post` middleware. HEAD, OPTIONS and TRACE operations are skipped. Use it to call another API's operations as URLs on your computer, with your own checks in the middleware. The instance then lists as type `sdk`. `GET /api/v1/exec/sdk/list` and `GET /api/v1/exec/sdk/{id}` inspect imports; `DELETE /api/v1/exec/sdk/{id}` removes one. See [SDK management](/api/exec/routing/#get-apiv1execsdklist). ## Security Scripts run with the authority of the Hoody Exec service, and neither mode isolates one script from another (the trust model on [Hoody Exec](/kit/exec/)). - Put sensitive operations behind a `// @token ` line ([Authentication](/kit/exec/authentication/)). `@token` protects requests to the script, not the Exec management API. Anyone who can reach that API can change scripts or remove their tokens. Set [proxy permissions](/foundation/proxy/permissions/) for the Exec service before sharing its URL. - Validate all user input. - Use the [computer firewall](/foundation/networking/firewall/) in production. ## Rate limits | Limit | Value | |---|---| | `/api/v1/exec/` endpoints | One shared limit: 100 requests per 60 seconds per client. Past it the answer is `429` with `retryAfter`, the seconds until the window ends, in the JSON body. | | Tracked clients | At most 10,000 at once. While that table is full, a client not yet tracked gets `429` with `retryAfter` `60` on its first request. | | Script routes | Requests to your scripts' own routes are not counted. | ## API by task All routes are relative to the instance, such as `https://PROJECT_ID-COMPUTER_ID-exec-1.SERVER.computers.hoody.com`. | Task | Routes | API page | |---|---|---| | Run a script | `POST /{path}`, through file-based routes | [Script execution](/api/exec/script-execution/) | | Manage script files | `GET /api/v1/exec/scripts/list` (one level; `recursive=true` for the files below), `GET /api/v1/exec/scripts/read`, `POST /api/v1/exec/scripts/write` (create or update), `DELETE /api/v1/exec/scripts/delete`, `POST /api/v1/exec/scripts/move` (move or rename), `POST /api/v1/exec/scripts/tree` (directory tree) | [Script management](/api/exec/script-management/) | | List exec instances | `GET /api/v1/exec/list` | [Script management](/api/exec/script-management/#execution-namespaces) | | Templates | `GET /api/v1/exec/templates/list`, `GET /api/v1/exec/templates/preview`, `POST /api/v1/exec/templates/generate` (create from a template); custom: `POST /api/v1/exec/templates/create-custom`, `PUT /api/v1/exec/templates/update-custom/{name}`, `DELETE /api/v1/exec/templates/delete-custom/{name}` | [Templates](/api/exec/templates/) | | Validate | `POST /api/v1/exec/validate/script` (comprehensive; `typecheck: true` also checks SDK calls), `POST /api/v1/exec/validate/typescript` (transpile check; `typecheck: true` type-checks against the installed Hoody SDK), `POST /api/v1/exec/validate/syntax`, `POST /api/v1/exec/validate/dependencies`, `POST /api/v1/exec/validate/return-type`, `POST /api/v1/exec/validate/magic-comments` (parse) | [Validation](/api/exec/validation/) | | Look up SDK signatures | `GET /api/v1/exec/sdk-types` | [Dependencies](/api/exec/dependencies/#look-up-sdk-methods) | | Dependencies | `POST /api/v1/exec/dependencies/check` (missing packages), `POST /api/v1/exec/dependencies/install` (npm modules), `GET /api/v1/exec/dependencies/bundled` (pre-bundled) | [Dependencies](/api/exec/dependencies/) | | Routes | `POST /api/v1/exec/route/resolve` (which script a URL maps to), `POST /api/v1/exec/route/discover` (all routes), `POST /api/v1/exec/route/test` (route matching) | [Routing](/api/exec/routing/#post-apiv1execroutediscover) | | `package.json` | `GET /api/v1/exec/package/read`, `POST /api/v1/exec/package/update`, `POST /api/v1/exec/package/install`, `POST /api/v1/exec/package/compare`, `POST /api/v1/exec/package/pin` (pin versions), `POST /api/v1/exec/package/init` | [Package management](/api/exec/package-management/) | | Magic comments | `GET /api/v1/exec/magic-comments/schema`, `GET /api/v1/exec/magic-comments/read`, `PUT /api/v1/exec/magic-comments/update`, `POST /api/v1/exec/magic-comments/bulk-update` | [Script management](/api/exec/script-management/#magic-comments) | | State and cache | `POST /api/v1/exec/shared-state/get`, `POST /api/v1/exec/shared-state/set`, `POST /api/v1/exec/shared-state/clear`, `POST /api/v1/exec/cache/clear` (execution cache) | [Cache and state](/api/exec/cache-state/) | | Logs | `GET /api/v1/exec/logs/list`, `POST /api/v1/exec/logs/read`, `GET /api/v1/exec/logs/stream` (SSE, `text/event-stream`), `POST /api/v1/exec/logs/search`, `DELETE /api/v1/exec/logs/clear` | [Logs](/api/exec/logs/) | | Monitoring | `GET /api/v1/exec/monitor/stats` (performance metrics), `GET /api/v1/exec/monitor/active-requests`, `GET /api/v1/exec/monitor/scripts` (per-script metrics, recent errors and VM-cache state), `POST /api/v1/exec/monitor/script-performance`, `GET /api/v1/exec/monitor/metrics` (Prometheus text; `404` when Prometheus is off), `GET /api/v1/exec/health` | [Monitoring](/api/exec/monitoring/) | | Schedules | `GET /api/v1/exec/schedules/list` (registered `@schedule` directives with next and last fire), `GET /api/v1/exec/schedules/history` (past fires and outcomes), `POST /api/v1/exec/schedules/trigger` (fire now), `POST /api/v1/exec/schedules/reload` (re-read `@schedule` from disk) | [Scheduling](/api/exec/scheduling/) | | Restart | `POST /api/v1/exec/system/restart`, `GET /api/v1/exec/system/restart-status` | [Monitoring](/api/exec/monitoring/#system) | | User OpenAPI | `POST /api/v1/exec/user-openapi/generate` (a spec from your scripts), `GET /api/v1/exec/user-openapi/list`, `POST /api/v1/exec/user-openapi/validate`, `GET /api/v1/exec/user-openapi/schema`, `GET /api/v1/exec/user-openapi/spec`, `POST /api/v1/exec/user-openapi/merge` | [Routing](/api/exec/routing/#get-apiv1execuser-openapilist) | | Imported SDKs | `POST /api/v1/exec/sdk/import`, `GET /api/v1/exec/sdk/list`, `GET /api/v1/exec/sdk/{id}`, `DELETE /api/v1/exec/sdk/{id}` | [Routing](/api/exec/routing/#get-apiv1execsdklist) | ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | Script returns `404` | No script file matches the URL path, or the matching script has `@enabled false` (no other script is tried). | Check the file exists, for example at `/hoody/storage/hoody-exec/scripts/default/1/path/to/script.ts`, that the filename matches the route exactly, and test it with the route validation API. | | Magic comments not working | The comments are not at the top of the file, or a name or value is invalid. | Follow the [placement and syntax rules](#magic-comment-rules), and parse them with the validation endpoint. | | Shared state not persisting | A restart, a clear, or eviction of that hostname's idle state. | `shared` is in-memory in both modes. Use the SQLite service for persistence. | | WebSocket connection fails | A missing magic comment, or the wrong mode. | The script needs both `// @mode worker` and `// @websocket`. Serverless mode cannot serve ordinary script [WebSocket connections](/kit/exec/execution-modes/#websocket-support-worker-mode-only). | | CORS errors in the browser | Not a missing comment, since reflective CORS is on by default. A script CORS comment may restrict the origin, or the response or preflight headers differ from what you expect. | Check the response and preflight headers. If the script restricts CORS, use [`// @cors reflective`](/kit/exec/magic-comments/#cors-configuration), or pin one origin. | | Script times out | A long-running operation exceeds the timeout. | See [timeouts](#timeouts) and the [`@timeout` comment](/kit/exec/magic-comments/#execution-and-performance). Optimize slow operations and consider async patterns. | | Concurrent request limit reached | The `@concurrent` limit is reached and requests are queuing. | Raise it (`// @concurrent 10`), optimize the script, consider worker mode for high traffic, and watch request activity through the monitoring API. | | Module not found after auto-install | The install failed, or a network issue interrupted it. | Check network connectivity, that the module exists on npm, the logs for install errors and the name's spelling; install manually if needed. |