Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Hoody Exec. Every route, field and response is in the Hoody Exec API reference.

WorkloadModeWhy
Instant APIs, internal tools (admin dashboards, data migrations, reports)EitherEach 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 toolsWorkerThe 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 poolsWorkershared persists across requests with zero overhead.
High request volume, frequently called endpointsWorkerLater requests reuse the cached context.
Webhook receivers (Stripe, GitHub, Slack)ServerlessA 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 contextServerlessBuilding a context per request costs less than keeping one alive.
PrototypingEitherIterate with magic comments, without a deploy step.
Hoody AI interception, proxy hooksWorkerBoth 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.
RuleDetail
Orderscripts/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 linksRegular routes found by scanning are tried first. Explicit-path symbolic links can then be followed before hostname or global index fallbacks.
.exclusiveAn 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.
defaultThe subdomain folder. Public exec URLs always serve from default.
Extra hostname labelA hostname with a name in front, such as myapp.{projectId}-{computerId}-exec-1.{server}.computers.hoody.com, does not reach your computer.
Exec IDLowercase 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 scriptA script with @enabled false answers 404, and no other script is tried.

Routing has dynamic routes, priority and middleware.

CallReturns
GET /api/v1/exec/listThe 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/listThe 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 typeIn 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:

Terminal window
# List the scripts of the exec instance
hoody exec scripts list -c "$COMPUTER_ID" -o json
RuleDetail
When readAt 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.
PlacementBefore 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.
SyntaxA space after //. Check the comment name’s spelling.
Syntax errorsA syntax error in the code stops the script from running but does not stop the comments being read.
CheckingThe validation API parses and checks them: POST /api/v1/exec/validate/magic-comments.
@corsReflective 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.
LoggingSet a logging level suited to your debugging.

Every comment is on Magic Comments.

CaseBehaviour
DefaultOne 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.
DeadlineA 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 timeThe 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 exceptionWhen 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 hooksA 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 codeSynchronous code that blocks the server for longer than its watchdog limit (30 seconds by default) gets the server restarted, whatever @timeout says.
RuleDetail
DefaultUnlimited concurrent requests in both modes. A worker handles them in its shared context.
@concurrent NCaps parallel runs, for example @concurrent 5 to prevent overload. Past the cap, requests queue.
@concurrent falseSerial processing, for example for webhooks.
ScopeApplies 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 controlManage concurrency yourself with semaphores or queues.
WatchingWatch request activity through the monitoring API.
RuleDetail
ScopeOne shared object per instance (hostname and exec ID), the same in worker and serverless mode.
Emptied byA computer restart, clearing it, or the service evicting that hostname’s idle state. Each empties it for new requests.
Open WebSocketsA WebSocket connection that is still open keeps the old object until it closes.
Serverless modulesModules you require or import can keep state between requests, so keep delivery-specific data out of them.
Remote functionsIn serverless mode, functions a script registers for remote messages and calls keep the variables of the run that registered them.
Worker contextBuilt by the first request, and again after a restart or cache eviction.
Old keysClean up keys you no longer need so memory does not leak.

State loss on restart has worked examples.

RuleDetail
DetectionPackages your script names with a plain string in require() or import are checked and installed with npm install. The install status is cached.
Computed namesA package named by a computed value, such as require(name), is not detected: install it first with the package management API.
VersionsThe 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 specifierrequire('lodash@4.17.21') fails with ERR_VERSIONED_SPECIFIER; pin it in package.json instead.
Always-available packagesAn 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-sdkInstalled 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 checkstypecheck: 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 run after a computer restart while at least one enabled script has @schedule; a script with @enabled false does not count.

CaseWhat happens
With schedulesHoody 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 schedulesIt stays stopped after a restart until something calls it.
Missed firesFires that fall while Hoody Exec is not running are skipped, not run late.
Stopped by youIf you stop the hoody-exec program yourself, a restart of Hoody Daemon alone does not start it again.

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.

FieldDefaultEffect
gracefultrueDrain in-flight requests before restarting. false exits at once.
drainTimeoutMs5000The 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.

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.

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). @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 for the Exec service before sharing its URL.
  • Validate all user input.
  • Use the computer firewall in production.
LimitValue
/api/v1/exec/ endpointsOne 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 clientsAt 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 routesRequests to your scripts’ own routes are not counted.

All routes are relative to the instance, such as https://PROJECT_ID-COMPUTER_ID-exec-1.SERVER.computers.hoody.com.

TaskRoutesAPI page
Run a scriptPOST /{path}, through file-based routesScript execution
Manage script filesGET /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 instancesGET /api/v1/exec/listScript management
TemplatesGET /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
ValidatePOST /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 signaturesGET /api/v1/exec/sdk-typesDependencies
DependenciesPOST /api/v1/exec/dependencies/check (missing packages), POST /api/v1/exec/dependencies/install (npm modules), GET /api/v1/exec/dependencies/bundled (pre-bundled)Dependencies
RoutesPOST /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.jsonGET /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/initPackage management
Magic commentsGET /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-updateScript management
State and cachePOST /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
LogsGET /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/clearLogs
MonitoringGET /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/healthMonitoring
SchedulesGET /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
RestartPOST /api/v1/exec/system/restart, GET /api/v1/exec/system/restart-statusMonitoring
User OpenAPIPOST /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/mergeRouting
Imported SDKsPOST /api/v1/exec/sdk/import, GET /api/v1/exec/sdk/list, GET /api/v1/exec/sdk/{id}, DELETE /api/v1/exec/sdk/{id}Routing
SymptomCauseWhat to do
Script returns 404No 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 workingThe 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 persistingA 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 failsA 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 browserNot 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 outA long-running operation exceeds the timeout.See timeouts and the @timeout comment. Optimize slow operations and consider async patterns.
Concurrent request limit reachedThe @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-installThe 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.