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 Daemons. Every route, field and response is in the API reference.

FieldDefault
enabled, logs_enabledtrue
boot, lazy_loadfalse
boot_if_existsunset
autorestart"unexpected"; quick-start "false"
priority999
delay_seconds0, a startup window of 1 second
directorythe user’s home directory, or /tmp when it cannot be found
stdout_logfile, stderr_logfile/hoody/storage/hoody-daemon/logs/<name>/stdout.log and stderr.log; port-range stdout_<port>.log and stderr_<port>.log
log_max_bytes, log_backups5 MiB per file, 2 rotated backups
inject_computer_envtrue for Hoody Kit programs, false otherwise
  • name: starts with an ASCII letter or digit, then ASCII letters, digits, ., -, _, up to 128 characters.
  • directory: an existing absolute path of ASCII letters and digits, /, _, ., -, spaces and tabs, with no .. component.
  • command: no line feed, carriage return or NUL. For a pipeline or redirection, use a wrapper script.
  • user: a dedicated account with only the privileges it needs; root only when required.
  • port_param: names the flag used to append the port, such as -p; valid only with port_range. See the management API.
  • terminal_shell: the shell that loads the environment, or tmux: an installed bash, zsh, fish, sh or tmux. Non-blank requires terminal_id; an empty or whitespace-only string means direct execution. See the management API.
  • terminal_interactive: overrides the automatic choice between an interactive shell and a replaced one. See the management API.
  • display: a Hoody Display number from 1 to 40000 for GUI programs. See Displays.
  • delay_seconds: a start-success threshold, not an inter-program delay.
  • Unknown fields: a repeated top-level key is a 400, and so is a near-miss such as sandbx when sandbox is absent. Other unknown top-level fields are ignored, so a misspelt name does nothing.
RuleDetail
NamesC identifiers (^[a-zA-Z_][a-zA-Z0-9_]*$), up to 128 characters.
ValuesStrings, with no line feed or carriage return.
Whitespace then ; or #400: the rest would read as a comment and the program could not load. A NUL, carriage return or line feed does not hide the pair. a;b and #fff are fine. A program with terminal_id and no port_range accepts it.
QuotesOne kind only, and none at either end. say "hi" now and it's here are fine; "quoted" and it's "both" are not. The 400 names the variable, never the value. A program with terminal_id, no port_range and a user other than root accepts it.
Saved earlierNot refused when an edit changes something else. Both quote kinds: left out and logged, the rest loads. A quote at either end: arrives without it.
%(ENV_NAME)sExpanded before the definition is read, which can break it if the variable holds a quote.
SandboxedStricter rule.

Both refusals apply on create, on an edit that sends the value, and on quick-start.

For a standard program without terminal integration, $NAME and ${NAME} expand from the daemon’s own environment when the definition is written, and an unknown name stays as written. A command with %(ENV_NAME)s gets no such expansion. Port-range commands are not substituted.

  • Without a path, the daemon uses the default directory and creates it. Rotation defaults are under program fields.
  • A custom path must stay under /hoody/storage/hoody-daemon/logs. Any other, such as /var/log/app.log, is a 400.
  • A missing directory is created only there, when every directory above is owned by root and not writable by other accounts, and no symbolic link is involved.
  • Otherwise, or when creating it fails, the program is saved but not written. The create, edit, enable or start that applies it names the directory and reason; a quick-start is a 400.

This is the set the computer’s init process holds.

inject_computer_envThe program receives
trueOrdinary programs: all of it. Kit programs: its HOODY_* variables. Daemon options --inject-all-env and --inject-hoody-env-only change that for every program. environment overrides, so clearing it does not empty the environment.
falseOnly variables the command references as $NAME, ${NAME} or %(ENV_NAME)s, plus the process manager’s own small environment (such as PATH, LANG) and environment.
  • ${NAME:-default}, ${NAME:+alt} and ${#NAME} are not references.
  • Through the process manager’s environment line, an injected or referenced value with both quote kinds is left out, and a quote at either end is stripped. A non-root terminal program passes them through its launcher instead. A sandboxed program leaves out any non-literal value.
  • Set values in environment to override injected variables. Unsupported quoting is refused with 400, but NUL characters are accepted and removed, and expansion expressions can change a value. Use literal strings without NUL or expansion syntax when you need exact bytes.
  • Programs created under earlier daemon versions, which gave every program this environment, now take the default. A running one picks that up the next time its definition is applied, which restarts it once.

An omitted field keeps its value. null also keeps it, except that it clears sandbox, port_range or terminal_id. Clearing port_range also clears an omitted port_param; clearing terminal_id also clears omitted terminal_shell and terminal_interactive. Create defaults do not apply.

FieldOn edit
environmentReplaces the map. {} clears it.
port_rangeNeeds start and end; replaces the range.
webhooksNeeds enabled and urls, which replace the stored ones. Omitted events, headers, timeout, retry stay; supplied headers replace the map. null does not clear.
sandboxAn object replaces the stored block as a unit, with no field merge, so resend every setting you want kept. null clears it; omitting it keeps it. The CLI guards against dropped settings, and the Hub sandbox editor refuses to save settings it cannot preserve.
boot_if_existsnull keeps it; "" clears it.

A partial port_range or webhooks is a 400 naming the field, such as missing field `end` .

SituationResult
CreateApplied only with a port_range, boot: true, lazy_load: true or an effective sandbox; otherwise at first start.
EnableThe same programs are applied, and a boot-enabled one can start at once.
Edit leaving it disabledRemoved from the process manager, which normally stops it.
Edit, enabled, with lazy_load, current or former port_range, current or former boot, or current or former sandboxApplied before returning; reloaded when the definition changed.
Edit of any other enabled programKeeps its old definition until its next start.
You seeIt means
Error after a changeApply failed after saving, and the error says so. Read it and the program before retrying.
Success on create, enable or editFor an ordinary program without a sandbox, the definition may not be applied. Check status and the daemon log.
Start refused during a changeAn edit, removal or reset hit the program while the start was prepared, and nothing started. Send it again once the change has finished. A change after the start was issued does not refuse it, and applies to the process it started.

Reset replaces the program list with the computer’s default list, removes old programs from the process manager, attempts a reload and applies the defaults. Every program you added goes, so save the list first with hoody daemon programs list -o json. It can report success when the reload fails, so check the daemon log and processes. A missing, unreadable or malformed default list refuses it and changes nothing, though a start being prepared can still be refused.

  • wait: true: a finished program answers status: "exited" with last_run, whatever the exit code. fatal is an error that also carries last_run.
  • timeout: budgets polling after configuration and the start request, not the whole request, and does not cancel the program. Quick-start too.
  • Finished runs are never ready: a finished run cannot satisfy a waiting start with ready_port or an on-demand lazy_load start; the start fails saying the program exited before accepting connections. One exception: if a waiting start joined a ready_port run that was already running, and that run exits before serving (a program that exits when idle), the start launches one successor when the old process shows as exited or still running and at least 2 seconds of its timeout remain. A stopped run is not restarted, and a run the start launched itself is never retried.
  • ready_port: an accepted connection shows something listens, not that the application is healthy. A crash before listening is a failed start.
  • A program that exits on its own has finished, however quickly. exited under "false" for any code or signal; under "unexpected" for code 0.
  • A program counts as started once it has stayed up for delay_seconds.
  • Under "true", an exit with code 0 starts again, at most once per window.
  • A command that cannot be executed ends fatal, with the reason in last_run.error; under "false" it is not retried.
  • A finished program can settle until the window ends, counted from the start: an edit or removal can take until then to return. A stop ends it at once.
  • A process manager or computer restart, or a reload of a changed definition, starts a boot: true program again, so a one-off boot command runs at every boot.
  • For a program reported as hoody_kit, an exit inside the window is a failed start, retried whatever autorestart says.
  • The port is appended as --port=<port> or <port_param>=<port>, so the command must accept that equals form.
  • -p VALUE, -p=VALUE, --port VALUE or --port=VALUE in the command suppresses this, and every instance runs on that port. An attached -p8000 is not recognised.
  • The range is inclusive, within 1 to 65535, at most 4096 ports, and cannot overlap another program’s.

boot_if_exists adds a start and never holds one back: a boot: true program starts at boot either way. Use boot: false, usually with lazy_load: true.

At each Daemon service start, an enabled program with the field starts when the path is a regular file (not a symbolic link or directory) and its status reads STOPPED Not started.

EventResult
Computer restart with markerStarts
Daemon service restart onlyA running program is left alone. A stopped one stays stopped until a computer restart with the marker.
ResetA program with a marker starts, even if you stopped it.
No markerNot started; a lazy program waits for its first request.
Setting the fieldStarts nothing. The file is not watched.

The value is an absolute path of at most 4096 bytes, with no .. segment or control character. A port_range wider than one port is a 400, on create or edit. The program is applied at start-up even without boot or lazy_load.

Webhook delivery is off by default. Saving a configuration does not establish that notifications will be delivered; poll program status for monitoring you rely on.

{
"webhooks": {
"enabled": true,
"urls": ["https://hooks.example.com/events"],
"events": ["FATAL", "BACKOFF"]
}
}
FieldRule
urls1 to 5 when enabled: HTTPS, no credentials, public destinations. A name resolving to a non-public address is saved, then refused at delivery (see the daemon log). A disabled configuration is not checked.
eventsSTARTING, RUNNING, BACKOFF, STOPPING, STOPPED, EXITED, FATAL, UNKNOWN, without the PROCESS_STATE_ prefix. Omitted, [], "all" or "*" selects all.
headersUp to 10.
timeout1 to 60 seconds, default 10, per attempt.
retry0 to 5, default 3. retry: 3 means up to four attempts. A refused destination is not retried.

Delivery is in-memory: nothing is queued across a daemon restart, order is not guaranteed, and a retry can deliver twice. Only 2xx succeeds, redirects are not followed, and proxy variables are ignored. Make the receiver tolerate duplicates and answer 2xx once it has accepted the event.

State events are matched to ordinary programs and port-range instances. Port-range webhook payloads include metadata.instance and metadata.port. Delivery requires notifications.enabled and notifications.event_listener_enabled set to true in /hoody/storage/hoody-daemon/config/config.json, and the daemon running as the process manager’s event listener for process state events. Saving a program’s webhook configuration alone delivers nothing.

StateMeaning
runningRunning normally, with a PID
stoppedNot running, or the process manager cannot be asked at all
starting, stoppingLaunching, or shutting down gracefully
backoffFailed to start, retrying
exitedRan and exited on its own
fatalFailed after retries, or could not be executed; needs manual intervention
unknownThe answer was unreadable: a lookup failure, or a state outside the known set. Quick-start: a status command that cannot answer.
failedQuick-start only: the definition never loaded, so nothing ran. last_run.error gives the reason.

supervisor_state appears when the process manager’s state differs, as when a run ended and the daemon is finishing up.

The monitoring API has every shape. In whole-list status a port-range program shows one summary, with no instances or last_run.

  • cpu_percent is a whole-life average and can exceed 100% for a multi-threaded program.
  • With the process manager unreachable, one program or instance can report stopped, no proof it ended. A whole-range read is an error; an empty instances means a successful read.

last_run appears once a run has ended, in status and start responses.

Field or caseReport
errorWhy it never ran (bad command, sandbox setup), or why the daemon ended it: ttl expired, daemon restarted before the program finished
sourcelauncher, or supervisor for the process manager’s record or the daemon’s own, such as ttl expired
Sandboxed or terminal program, signal deathexit_code 128+n (137 for SIGKILL, 143 for SIGTERM), signal null
Only the process manager’s record (run ended during a daemon restart; always for Kit programs)signal null; exit_code as recorded, null after a signal death
Could not be spawnederror is the spawn error, exit_code null
Exited too quickly to count as startedWith only the process manager’s record, error reads Exited too quickly (process log may have details) and exit_code is null. With the launcher’s report, exit_code is the real exit code

Port filters match port_range only, never a port in the command or ready_port. Combined filters, include_status, include_stats and query errors are in the management API.

  • Errors: disabled logging, a missing file, or an unreadable file.
  • Window: only the final 10 MiB. A partial line at its start is dropped; a line longer than the window comes back as its truncated tail.
  • Encoding: invalid UTF-8 comes back as replacement characters.
  • Files: the current file only. For persistent programs with both log paths omitted, the defaults are symlinks to timestamped files; old session files past retention (30 days by default) are deleted when a changed definition is applied. Copy what you need through the Files service, which can also tail them.

The API reference covers the rest.

TopicRule
ttlOptional, in seconds, counted from launch across retries and restarts. expires_at is the deadline. Expiry checks run every 10 seconds, so stopping can happen later. On expiry, last_run.error reads ttl expired. Without ttl, there is no timed expiry.
Daemon restartFinished programs keep their remaining retention.
Repeat requestRuns it again.
On diskCommand and environment are written while it runs. The definition goes when it finishes, stops or expires; the recovery record lasts through retention.
FinishedIncludes failed, but not an exit autorestart will restart.
NamesNot unique. Same-name runs share default log paths, so use distinct ones.
Waiting, default autorestartNon-zero exit: HTTP 200, status: "exited". Under "unexpected" or "true", a non-zero exit in the window is retried and can end fatal.

A program with terminal_id: N owns terminal N while it is configured. Attach to it or request a terminal snapshot after starting it. Without a connection, output can fill the terminal buffer and block the program. Once connected, the terminal continues consuming output after clients disconnect. If the program restarts, connect again. The stdout log may omit output when no terminal connection is reading it or when the log cannot keep up.

Open it like any terminal:

Terminal window
# By id or by exact name. Ctrl-] detaches; --read-only watches without sending keys.
hoody daemon programs terminal connect web-console -c "$COMPUTER_ID"
hoody daemon programs terminal connect 12 --read-only -c "$COMPUTER_ID"
SituationWebSocketREST automation
RunningAttachesWorks
Stopped or not startedCloses 4404 daemon program not running409 DAEMON_PROGRAM_NOT_RUNNING
Ends while attachedCloses 4404 daemon program endedA pending wait answers exited
RestartedA new attach reaches it on a clean screen, at the clients’ sizeWorks
A shell opened on the id firstCloses 4409409 DAEMON_TERMINAL; delete that session
  • Image: keep its base packages installed.
  • Size: 0x0 until the first attach or REST call; kept when the last client leaves. The smallest reported width and height among writable clients set it, with SIGWINCH. If no writable client has reported a size, the smallest among read-only clients sets it instead.
  • Clients: Ctrl-C reaches the program. Read-only is a per-connection choice, not a permission: any client that can reach the terminal can attach writable.
  • REST: snapshot, find, press, mouse, paste, write, wait, raw and screenshot connect on demand. Shell, working directory, user, environment, display, cmd and pid parameters are ignored. Nothing is spawned: /execute, creating a session and the display redirect answer 409 DAEMON_TERMINAL.
  • Session list: the daemon object has running (ready to connect) and ended (while attached). pid is the session leader while connected, else 0; cols, rows are null until sized. A local shell on the id stays listed as that shell, with daemon_program: false and the program in daemon. DELETE /api/v1/terminal/N disconnects clients and leaves the program running.
  • Reconnects: the browser retries while stopped. The SDK stops at 4404. The CLI retries 4404 daemon program not running for up to 5 seconds when status is starting or running; otherwise it stops.

List all programs to see the Kit services in your computer, such as hoody-terminal. The Daemon service is not among them. To change a Kit service’s flags, edit its program’s command; see change a Kit service’s flags.

The service manager starts the Daemon service through /hoody/storage/hoody-daemon/scripts/startup.sh. Root owns it, anyone can read it, changing it takes sudo, and updates keep your changes. Use it for a Daemon service variable or a step before start:

#!/bin/bash
export MY_VAR=value
cd /hoody/storage/hoody-daemon || exit 1
exec /hoody/plugins/daemon/hoody-daemon "$@"
  • Program variables belong in their environment.
  • Keep the last line: "$@" passes the service manager’s options, and exec hands over the script’s place.
  • A change applies at the next start, such as sudo systemctl restart hoody-daemon, and the API does not answer during it.
  • Options: systemctl cat hoody-daemon (ExecStart), /etc/init.d/hoody-daemon or root’s crontab.
SymptomCauseFix
backoff or fatalFailing command, port in use, missing dependencies, wrong permissionsRead last_run and stderr. Run the command as that user.
Edit had no effectProgram not applied on edit, or environment replacedStop and start it. Read it back; resend the full map.
No auto-restartautorestart: "false", disabled, or fatalSet "true", enable it, read the stderr and daemon logs.
Stops right after startExited, no keep-alive, or detachedRead last_run. Keep services in the foreground; a one-off should end exited.
Computer variable missinginject_computer_env is falseSet it true, or use environment.
Priority ignored at bootAt boot, programs are applied one at a time, so priority cannot make one wait; or no boot: trueRetry until dependencies answer; confirm enabled with boot: true.
Wrong stateNo status cache: no answer, an unreadable answer (a whole-range read skips such lines), or a process detached or killed outside the managerRead again, confirm with ps. Restarting the daemon refreshes nothing.