Skip to content

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

Hoody.com

Lookup tables for remote messages and events, the operations a live Hoody Exec script answers on its own URL.

The operations table on the guide names each operation, its marker and the comment it needs. Beyond it:

  • Query form: events also answers GET ?hoody-remote=events, for a client that cannot set headers.
  • Bodies: send takes { "message": … } and call takes { "name": "…", "args": [ … ] }.
  • Version header: every answer to a marked request that remote dispatch handles carries X-Hoody-Remote-Version: 1, which confirms that the server supports remote operations.
  • When it is missing: on OPTIONS requests (answered with 204 before remote dispatch) and on requests refused before dispatch, such as one with a malformed URL. Only treat its absence on a normal response as “not supported”.
  • Refused markers: a request that sends the header twice, names an unknown operation, or puts any value other than events in ?hoody-remote= is refused with 400 REMOTE_UNKNOWN_OP. The marker is never silently ignored.
  • Methods: events and capabilities are GET; send, call and eval are POST. Another method answers 405 REMOTE_METHOD.
  • Execution modes: remote operations work in both execution modes. Background work that outlives the request belongs in worker mode, where the script’s context stays alive between requests.
  • Scopes: @remote-eval also needs a @remote-token with the eval scope. A token without a scope gets messages,call; eval is never implied. @remote-token is repeatable.
  • Capability values: the three capability comments take no value, or exactly true or false. Any other value is ignored: that line has no effect, and if the comment appears more than once, the last valid line wins.
  • Token names: 1 to 64 letters, digits, dots, underscores or hyphens, and each name may appear once.
  • Secrets: written inline or read from the script’s .env companions with env:NAME, which keeps the secret out of the script file and its history. A secret shorter than 16 characters, or an env: name with no value, matches nothing.
  • A line that does not parse: still counts as declared and matches nothing, so a typo in the values locks the script instead of opening it.
  • Spelling: the comment must be spelled exactly, // @remote-token followed by a space. A bare // @remote-token with nothing after it counts as a declared token that matches nothing. A line spelled differently is not recognised and protects nothing.
  • Position: like every magic comment, @remote-token lines must sit in the first 30 lines of the file, before any code; one further down is ignored.
  • Through the API: you can also set these comments through the magic-comments API. Every refusal for a disabled capability carries details.fix with both the comment to add and the exact magic-comments/update call.

remote.emit(event, data) sends one frame to every client listening to the script at that moment.

RuleDetail
eventA string of 1 to 128 characters. attached, end, console and generation are reserved for the server’s own frames and throw a TypeError
dataPlain data (what can be sent), at most 8 MiB once serialized. A value that cannot be sent throws a TypeError naming the first bad path; one over 8 MiB throws a TypeError saying it is too large
Return value{ delivered, dropped }: how many clients received the frame, and how many could not take it because their queue was full (those clients are disconnected with reason overflow)
No listeneremit returns { delivered: 0, dropped: 0 } and does no serialization work
Who can emitAny run of the script: an HTTP request, a @schedule fire, a send or call handler, or background work the script started
ReconnectsNothing is replayed when a client reconnects
Frame sizeEach frame is serialized once and queued per client; large payloads fill slow clients’ queues first, so emit small frames

Rooms: a deployment is the hostname together with its exec ID. An event emitted while handling /rooms/42 through rooms/[id].js never crosses to another exec ID or subdomain.

  • Format: the stream opens with an : open comment, then sends each frame as one data: line holding a JSON object, and a : ping comment every 15 seconds while the connection keeps up.
  • No event: field: frames carry no SSE event: field, so an EventSource delivers all of them to onmessage; the frame’s own event member tells them apart.
  • Other origins: remote answers carry the script’s CORS headers (reflective unless the script sets @cors), so a page on another origin can connect.
  • ?tail=: console.log counts as info. Without tail, no console lines are sent.
  • Waiting: a client that connects before anything emits simply waits.
eventShapeWhen
attached{ "event": "attached", "v": 1, "generation": "…", "path": "default/1/jobs/build.js" }First frame of every stream and socket; path is the script’s path from the scripts root
your event name{ "event": "progress", "data": { "pct": 50 }, "generation": "…" }Each remote.emit
console{ "event": "console", "level": "info", "args": [ … ], "kind": "…" }Each console call at or above the tail level. console.dir and console.table are not included
generation{ "event": "generation", "from": "…", "to": "…" }A changed version of the script takes over the handlers (or, with @remote-eval, the run scope) of the previous one
end{ "event": "end", "reason": "evicted" }Last frame, when the server ends the stream

generation identifies the version of the script’s source that produced a frame. A run that only emits does not send a generation frame itself, but its events still carry the new generation. A send or call to a rewritten script sends one even when the script registers no handler, provided the room already holds an earlier version, which any earlier send or call in that room sets up. With @remote-eval, a run that only emits can send one too.

end reasonAttach close codeCause
revoked4401 or 4403The token that opened the stream no longer admits it, or @remote-messages was removed. The frame also carries status and error. An attach socket gets a { "ok": false, … } refusal frame instead (see revoking a token)
evicted1001The script was deleted, disabled with @enabled false, switched to the other @mode, its URL now leads to another script, or the deployment was dropped (in worker mode, also when a .env file the script reads is written, moved or deleted through the management API, or the instance’s cache is cleared; in serverless mode, also when its whole shared state is cleared or replaced)
overflow1013The client’s queue (1,000 frames or 8 MiB, frame overhead included) filled, usually because it read too slowly. One event close to 8 MiB can cause it on its own
shutdown1001The Exec service is stopping

A client that disconnects ends its own stream. In the SDK and CLI the iteration ends with the stream. Treat revoked as final unless you have a new token. The SDK does not yield a revoked frame: the loop throws the refusal instead (SDK errors).

A handler registered with remote.on('message', fn) or remote.expose(name, fn) receives the message (or the call’s arguments) followed by a context object:

FieldValue
opThe operation
fromhttp or attach
tokenThe accepted token’s name, @token, or null
paramsRoute parameters
generationThe script version
signalAn AbortSignal that fires at the deadline or when the caller disconnects

The request body is a JSON object of at most 1 MiB. timeoutMs is optional and is capped by the script’s @timeout. The reply or result must be plain data (what can be sent) and at most 8 MiB.

Event data, replies and results are converted to JSON with these rules:

  • Own enumerable data properties are sent. A toJSON method is not called, and getters are never run.
  • undefined object members are left out, and a top-level undefined is sent as null. NaN and infinite numbers become null.
  • A valid Date becomes an ISO string (an invalid one null), a BigInt a string, a Map an array of [key, value] pairs and a Set an array. An Error becomes { name, message, stack }. An ArrayBuffer or typed array becomes a base64 string.
  • Functions, symbols, boxed primitives, getters and setters, proxies and circular references are refused, as is anything nested more than 256 levels deep or holding more than 1,000,000 values.

Every run of the script registers its handlers again, so a rewritten script answers with its new code. When no run of the current version has registered a handler in the room yet, the first send or call runs the script once, with metadata.method set to REMOTE_INIT, and then delivers the operation. Operations that arrive together share that one run.

SituationWhat happens
ConcurrencyThe REMOTE_INIT run that send or call starts, and every handler call, count against @concurrent, like any other run of the script. Eval does not: it runs outside @concurrent, including the run it starts with start: true
Waiting for a handlerAn operation that starts or joins the REMOTE_INIT run waits until the handler it needs is registered (the message handler for send, the named function for call), not for the rest of the run. If the run ends without registering it, the operation fails with REMOTE_NO_MESSAGE_HANDLER or REMOTE_FUNCTION_NOT_FOUND. Later operations that find their handler already registered skip the wait, but still need a free @concurrent slot. Register handlers once everything they use is ready
The REMOTE_INIT run throwsIt takes back the handlers it registered (not ones another run has since replaced them with): an operation still waiting for its handler gets 500 REMOTE_INIT_FAILED, and the next operation runs the script again if no handler is left. An operation that had already picked its handler, including one waiting for a @concurrent slot, still runs it
An older version runs lateIt never replaces the current version’s handlers. An operation sent to the older version while a newer one came in gets 409 REMOTE_SCRIPT_CHANGED: its handler did not run, and sending it again reaches the new version. An operation that had already picked its handler before the newer version came in, for example one waiting for a @concurrent slot, still runs the older handler
DeadlineAn operation that reaches its deadline gets 504 REMOTE_TIMEOUT. A handler that is already running is not stopped: ctx.signal aborts, and the handler runs to its end. One still waiting for a @concurrent slot is dropped and never runs
The handler throwsThe answer is 422 REMOTE_THREW, with the error in details.error

An attach socket carries events, send and call on one connection. Open a WebSocket on the script’s URL offering the subprotocol hoody-remote.v1; ?tail= works as for events. The first frame is attached, followed by the same frames an events stream gets, except that a revoked token ends the socket with a { "ok": false, … } refusal frame rather than an end frame.

FrameShape
Send{ "id": 1, "op": "send", "message": … }
Call{ "id": 2, "op": "call", "name": "pause", "args": [ … ] }
Answers (echo the id){ "id": 1, "ok": true, "reply": … }, { "id": 2, "ok": true, "result": … }, or { "id": 1, "ok": false, "status": 403, "error": { … } }
  • Text frames: each one is JSON text. eval is refused on a socket.
  • Limits: a socket can have 256 operations running at once (429 REMOTE_TOO_MANY_INFLIGHT beyond that) and closes with code 1009 on a frame larger than 1 MiB.
  • Re-check per frame: every send or call frame that passes these limits checks the script again, against its file as it is at that moment, before it runs; a frame refused earlier (not JSON, an unknown op) does not.
  • Token scope: a call-only token works over HTTP but cannot attach.
  • Token in a browser: browsers cannot set headers on a WebSocket. The token travels as a second subprotocol entry, hoody-token.<base64url of the token>, which the server reads and never echoes. The SDK does this for you.
  • SDK: ws: true moves send, call and streamEvents onto one attach socket (a streamEvents iteration with tail opens a socket of its own), and conn.connect() opens an explicit session with send, call, streamEvents() and close().

The latest run that eval targets is the most recently started run of the current version, whether it is still in flight or already finished. eval is always a one-shot POST, never an attach frame, and it is not held back by @concurrent.

FieldMeaning
expressionThe code to evaluate
function, argsA function’s source, called as fn(ctx, ...args), instead of expression
target"globals" evaluates in the worker context’s globals instead and needs @mode worker. It needs no earlier run: it ignores start and answers with "run": null
startWith the default target, true runs the script once first when no run scope is available; without it, such a request gets 409 REMOTE_NO_RUN
timeoutMsOptional
  • Answer: { "ok": true, "result": …, "logs": [ … ], "run": { … }, "durationMs": …, "generation": "…" }, where logs holds the console lines the evaluated code wrote. console.dir and console.table output is not included.
  • Log capture: stops at 1,000 lines or 1 MiB of text; when it stops early, the answer also carries "logsTruncated": true.
  • Scope kept: each room keeps only its latest finished run scope, and finished scopes are kept for at most 32 rooms per deployment, so an older one can be gone even though its script already ran.
  • 409 REMOTE_SCOPE_UNAVAILABLE: the latest-run target returns it if the script binds or assigns to eval, uses with, or replaces the global eval. In worker mode, target: "globals" still works then, but it reaches only the globals, not the run’s local variables.

The order in which tokens admit a request is on the guide under Protect the channel with tokens. @token and a missing token never unlock eval: it always needs a @remote-token with the eval scope.

  • Where to send it: as X-Token, Authorization: Bearer, the password of Authorization: Basic, ?token=, or a hoody-token.* subprotocol entry on attach. The SDK sends it only as X-Token or the subprotocol entry, never in a URL.
  • ?token=: by default, the Exec service removes a ?token= value before it logs the request, but a URL can still end up in browser history. Use the SDK, the CLI or a header wherever the client allows it.

For an HTTP refusal, match the remote code in details.code. The top-level code is ERROR_<status>; details.layer identifies the layer. For example: { "error": "...", "code": "ERROR_403", "details": { "code": "REMOTE_MESSAGES_DISABLED", "layer": "capability" }, "timestamp": "..." }.

CodeStatusMeaning
REMOTE_TOKEN_REQUIRED401The script needs a token and none was sent
REMOTE_TOKEN_INVALID401The token matches none of the script’s tokens
REMOTE_TOKEN_SCOPE403The token is valid, but its scope does not cover this operation (other than eval)
REMOTE_EVAL_TOKEN_REQUIRED403eval needs a @remote-token with the eval scope; other tokens, @token and open access do not admit it
REMOTE_MESSAGES_DISABLED403The script has no @remote-messages
REMOTE_CALL_DISABLED403The script has no @remote-call
REMOTE_EVAL_DISABLED403The script has no @remote-eval
REMOTE_EVAL_NEEDS_WORKER409The globals target needs @mode worker; use latest for a serverless script
REMOTE_BAD_BODY400The request body or operation parameter is invalid, too large, or could not be read; see details.reason
REMOTE_RESULT_TOO_LARGE413The serialized reply or result exceeds 8 MiB
REMOTE_RESULT_UNSERIALIZABLE422The reply or result cannot be sent as JSON; details.path names the value
REMOTE_NOT_A_SCRIPT400The remote operation addresses a documentation (.md) URL

An open stream or socket is checked again on every 15-second ping, against the script as it is on disk at that moment, and when a changed version of the script starts a run, before that run’s frames are sent.

ChangeEffect on open streams
Removing or rotating a token, removing messages from its scope, or removing @remote-messagesThe streams that token opened end within about 15 seconds, unless another current token still accepts the credentials they connected with
Removing only call or eval from its scopeThey stay open
A run of an older version of the script, for example one that waited behind @concurrentNever ends a stream that the current file still admits
Removing the last @remote-token lineHands remote operations back to @token, or to no token at all when the script has none, so a stream the fallback admits stays open

The re-check applies the same token order as a new connection.

The client receives the refusal it would get if it connected now: a final { "event": "end", "reason": "revoked", "status": 401, "error": { … } } frame on an events stream, or a { "ok": false, "status": 401, "error": { … } } frame followed by close code 4401 or 4403 on an attach socket. On both, the status is 403 instead of 401 when the token lacks the scope or @remote-messages is gone. The exception is a .env write through the management API in worker mode, which ends the stream as evicted instead.

Besides what the guide lists, capabilities reports the script’s latest run (recorded only for scripts with @remote-eval, otherwise null) and the number of open streams; for a script with no remote comment at all, these two are left out. The handlers and exposed functions are those registered by its current version.

hoody exec remote <op> <target> [args...], where <op> is capabilities get, send, call, evaluate, events stream or connect, takes as <target> the script’s URL, or a script path on the exec service of the computer chosen with -c. Arguments are JSON when they parse, otherwise text.

OptionUse
--remote-token, --remote-token-file <path|->, HOODY_EXEC_REMOTE_TOKENThe script token. The global --token is the auth token, not this. --remote-token is visible to other local users in the process list, so prefer the file or the variable
--index <n>Exec service instance for a script path (default 1)
--timeout-ms <ms>send, call, evaluate: the timeoutMs sent to the script. Every operation: how long the CLI waits for an answer (for events stream and connect, for the stream or socket to open), plus 5 seconds
--target, --start, --file <path|->evaluate: latest (default) or globals, run the script first, read the source from a file or stdin
--tail <level>, --count <n>, --timeout <duration>events stream: console level; events stream and connect: stop after n frames or after this long
--json-argssend, call, connect: refuse arguments that are not JSON
--wssend, call, events stream: use the attach socket instead of HTTP

Exit codes: 0 OK, 1 failure, 2 usage, 3 permission (a capability is off, or the token’s scope), 4 token (missing, wrong, or eval needs an eval token), 5 the script threw, 124 timeout, 130 interrupted.

The SDK’s computerClient.exec.remote(path, { token, ws }) returns a connection with getCapabilities, send, call, evaluate, streamEvents and connect. The SDK throws a refusal as an error, such as ExecRemoteTokenError for a token problem or ExecRemotePermissionError for a capability that was switched off.

LimitValue
Open streams and sockets per room64 (429 REMOTE_TOO_MANY_SESSIONS for the next one)
Rooms kept per deployment256 in all. Creating a room past that drops the least recently used idle rooms; rooms in use are kept, so the total can go over 256. A dropped room loses its registered handlers, and its next send or call runs REMOTE_INIT again
Queued frames per client1,000 frames or 8 MiB, then overflow
Event name, function name128 characters
Exposed functions per room1,024 names; exposing another new name throws a RangeError (replacing an existing one is allowed)
Event data, reply, call result8 MiB serialized
send / call request body, attach frame1 MiB
Operations running on one attach socket256
Keep-alive and token re-checkevery 15 seconds
SymptomCauseFix
403 REMOTE_MESSAGES_DISABLEDThe script has no @remote-messagesAdd // @remote-messages. The error’s details.fix holds the comment and the API call
401 REMOTE_TOKEN_INVALID with a correct @tokenThe script declares a @remote-token, which replaces @token for remote operationsSend one of its @remote-token tokens
409 REMOTE_NO_MESSAGE_HANDLERThe script never calls remote.on('message', …)Register a message handler
404 REMOTE_FUNCTION_NOT_FOUNDNo remote.expose with that namedetails.exposed lists the names that exist
409 REMOTE_SCRIPT_CHANGEDThe script was replaced while the operation waited, so its handler did not runSend it again and it reaches the new version
The stream opens but no events arriveNothing emitted since the client connected, or the emitting run handled another route parameter value (another room)Emit after the client connects, in the room it listens to
A browser EventSource keeps reconnecting after endEventSource reconnects on its ownCall source.close() when a frame has event: "end"
405 REMOTE_METHODThe wrong method for the operationevents and capabilities are GET; send, call and eval are POST