Hoody Exec reference
Section titled “Hoody Exec reference”Lookup tables for Hoody Exec. Every route, field and response is in the Hoody Exec API reference.
Which mode fits
Section titled “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 and Proxy Hooks. |
- Keep scripts small and focused (under 200 lines), and watch request latency through the monitoring API.
Script lookup order
Section titled “Script lookup order”| Rule | Detail |
|---|---|
| Order | scripts/default/<execId>/, then scripts/default/, then scripts/<execId>/, 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 has dynamic routes, priority and middleware.
Instance and script lists
Section titled “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. The CLI and SDK call exec instances namespaces (hoody exec namespaces list). |
List one instance’s scripts:
# List the scripts of the exec instancehoody exec scripts list -c "$COMPUTER_ID" -o jsonconst scripts = await computerClient.exec.scripts.list();console.log(scripts);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.
https://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-exec-1.SERVER.computers.hoody.com/api/v1/exec/scripts/list&method=GET&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
Magic comment rules
Section titled “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.
Timeouts
Section titled “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 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
Section titled “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. |
Shared state and context
Section titled “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 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 has worked examples.
Packages and auto-install
Section titled “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. |
| 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 and Type-check a script. |
Writing Scripts lists the pre-installed packages.
Schedules after a restart
Section titled “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). |
| 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
Section titled “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.
Imported SDKs
Section titled “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.
Security
Section titled “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).
- Put sensitive operations behind a
// @token <secret>line (Authentication).@tokenprotects 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 for the Exec service before sharing its URL. - Validate all user input.
- Use the computer firewall in production.
Rate limits
Section titled “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
Section titled “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 |
| 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 |
| List exec instances | GET /api/v1/exec/list | Script management |
| 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 |
| 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 |
| Look up SDK signatures | GET /api/v1/exec/sdk-types | Dependencies |
| 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 |
| 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 |
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Restart | POST /api/v1/exec/system/restart, GET /api/v1/exec/system/restart-status | Monitoring |
| 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 |
| 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 |
Troubleshooting
Section titled “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, 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. |
| 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, or pin one origin. |
| Script times out | A long-running operation exceeds the timeout. | See timeouts and the @timeout comment. 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. |