Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Daemon Management

Section titled “Daemon Management”

The Hoody Container Daemon supervises long-running programs through supervisord. This page documents the endpoints for listing, inspecting, creating, editing, removing, and resetting supervised programs, plus launching and managing ephemeral (Quick Start) programs. Use these endpoints whenever you need to add a custom service to a container, change an existing program’s settings, run a one-off task, or reset to a clean default configuration.

All endpoints in this page are reached through the container’s daemon-1 hostname: https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com.

Programs

Section titled “Programs”

GET /api/v1/daemon/programs

Section titled “GET /api/v1/daemon/programs”

Lists every configured program. Combine the filters to narrow the result by hoody_kit, lazy_load, enabled, or boot status. Use the port filters to find the program that owns a specific port or that overlaps with a port range, and name for an exact match on a single program. Pass include_status=true to attach runtime status to each entry, or include_stats=true for CPU and memory stats.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
hoody_kitquerystringNoFilter by hoody_kit status. Use "true" for Kit programs only, "false" for user programs.
lazy_loadquerystringNoFilter by lazy_load status. Use "true" for lazy-loaded programs, "false" for the others. A non-lazy program starts on its own only when it is enabled and has boot: true.
enabledquerystringNoFilter by enabled status. Use "true" for enabled programs, "false" for disabled.
bootquerystringNoFilter by boot status. Use "true" for auto-start on boot, "false" for manual-start.
namequerystringNoFilter by exact program name, for example hoody-agent. The value is validated with the same rules a program name is validated with on write, so a malformed name returns HTTP 400 rather than an empty result. This is the only filter that selects one specific standard program: a program with no port_range cannot be matched by the port filters.
portqueryintegerNoFilter by a single port, 1 to 65535. Returns only programs whose port_range includes this port. Example: ?port=8042.
port_fromqueryintegerNoFilter by port range start, 1 to 65535. Must be used with port_to. Returns programs whose port ranges overlap using program.start <= port_to AND program.end >= port_from.
port_toqueryintegerNoFilter by port range end, 1 to 65535. Must be used with port_from.
include_statusquerystringNoInclude runtime status for each program. Adds a status field with the current state, instances, and process details.
include_statsquerystringNoInclude CPU and memory stats. Turns status on only when include_status is omitted: an explicit include_status=false suppresses both. Adds a stats field with pid, started_at, cpu_percent, memory_rss_bytes, process_count, and a per-process breakdown. Only present for running programs.

Response

Section titled “Response”
Terminal window
hoody daemon programs list --include-status true -c "$CONTAINER_ID"

GET /api/v1/daemon/programs/{id}

Section titled “GET /api/v1/daemon/programs/{id}”

Retrieves detailed configuration for a single program by its numeric ID.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program. An id that is not a valid i32 (a word, an empty segment, a number too large) never reaches the handler: the path extractor refuses it with a plain-text 404, on every route that takes an id, which is NOT the documented JSON 404 of the routes that have one. An id that parses but names no program: on routes that document a 404 (this route does), returns the documented JSON 404 envelope ({success: false, error:...}); on the other routes, returns a 400 carrying the {success: false, error:...} envelope.

Response

Section titled “Response”
Terminal window
hoody daemon programs get 1 -c "$CONTAINER_ID"

GET /api/v1/daemon/programs/{id}/sandbox

Section titled “GET /api/v1/daemon/programs/{id}/sandbox”

Reports what the daemon would enforce for this program’s stored sandbox policy and what the kernel is currently holding for it. effective is derived from the stored policy; live.table_present and live.rules are read back from nftables at request time and live.chain is derived from the stored revision, so the two disagreeing is itself the finding. A program with no effective sandbox answers 200 with rev: null and effective: null; configured carries the stored block or null. A policy that no longer validates or an unreadable state file does not fail the request: it is reported in problems with firewall: degraded.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program. An id that is not a valid i32 (a word, an empty segment, a number too large) never reaches the handler: the path extractor refuses it with a plain-text 404, on every route that takes an id, which is NOT the documented JSON 404 of the routes that have one. An id that parses but names no program: on routes that document a 404 (this route does), returns the documented JSON 404 envelope ({success: false, error:...}); on the other routes, returns a 400 carrying the {success: false, error:...} envelope.

Response

Section titled “Response”
Terminal window
hoody daemon programs sandbox get 1 -c "$CONTAINER_ID"

POST /api/v1/daemon/programs/add

Section titled “POST /api/v1/daemon/programs/add”

Creates a new daemon program from a JSON request body. The program is validated and persisted to programs.json. Its supervisord definition is written at once only when it is enabled and has boot, lazy_load, a port_range or an effective sandbox; an enabled boot: true program is therefore applied during this call and can start at once. An ordinary program is registered when it is first started. A sandboxed program whose definition cannot be applied is a 400 AFTER it was persisted; an ordinary program’s apply failure does not fail the request.

For custom programs only (your own code/scripts), not system services.

Correct examples: node app.js, python my_script.py, ruby custom_server.rb, ./my-binary Wrong examples: apache2, nginx, postgresql, mysql; use systemctl for these.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
idintegerNoSpecific id to assign, 0 to 2147483646. Auto-assigned when omitted.
namestringYesProgram name. Must be unique, start with a letter or digit, contain only letters, digits, ., - and _, up to 128 characters.
descriptionstringNoHuman-readable description.
commandstringYesCommand to execute with full arguments for your custom program. Must not contain a line feed, carriage return or NUL.
userstringYesSystem user (must exist on the system). A Linux account name matched case-insensitively: starts with a letter or _, continues with letters, digits, _ and -, may end in $, at most 32 bytes. A sandboxed program cannot run as an account resolving to uid 0.
enabledbooleanNoEnable the program immediately. Default: true.
bootbooleanNoStart automatically on system boot. Default: false.
delay_secondsintegerNoSeconds the program must STAY RUNNING for supervisord to consider the start successful (supervisord’s startsecs). The program is launched immediately. 0 does NOT disable the window: the daemon writes startsecs=1 at 0. Under autorestart "unexpected" or "true", a non-zero exit or a signal inside the window is a failed start, retried up to startretries times and then fatal. An end that is not a crash under autorestart (any end under "false", an exit 0 otherwise) is not a failed start, however quick: it is kept from supervisord until the window has passed, so a one-shot runs once. Under "false" and "unexpected" it is reported as exited as soon as it ends, with its exit code or signal in last_run; under "true" it is started again once the window has passed. A stop, edit or removal sent in that window can take up to this long to return. Hoody Kit programs keep supervisord’s own rule: any exit inside the window is a failed start, whatever autorestart says. Default: 0.
autorestartstring | booleanNoRestart policy: "unexpected" (default) restarts after an exit code other than 0, including a deliberate nonzero exit; "true" always; "false" never. Booleans true/false are accepted too and are stored and returned as sent. A program that exits on its own has finished, however quickly: any end under "false", and an exit 0 under "unexpected", is reported as exited with its result in last_run, so a one-shot runs once; under "true" an exit 0 is held until delay_seconds has passed and then started again. Under "unexpected" and "true" a non-zero exit or a signal inside the delay_seconds window is still a failed start, retried up to startretries times and then fatal. Hoody Kit programs keep supervisord’s time-based rule. Default: "unexpected".
directorystringNoWorking directory: an absolute path of ASCII letters and digits, /, _, ., -, space and tab, with no .. path component, that must exist. Defaults to the user’s home directory, or /tmp.
priorityintegerNoStart priority, lower starts first. Default: 999. Any u32 is accepted; no range is enforced.
stdout_logfilestringNoPath for standard output log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Defaults to /hoody/storage/hoody-daemon/logs/<name>/stdout.log.
stderr_logfilestringNoPath for standard error log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Defaults to /hoody/storage/hoody-daemon/logs/<name>/stderr.log.
logs_enabledbooleanNoWhether logging is enabled. Default: true.
log_max_bytesintegerNoMaximum size of each log file in bytes before rotation. Default: 5242880 (5MB).
log_backupsintegerNoNumber of rotated backup log files to keep. Default: 2.
environmentobjectNoEnvironment variables as key-value pairs. Names match ^[a-zA-Z_][a-zA-Z0-9_]*$ (up to 128 characters); values must not contain a line feed or carriage return. A value may not hold both a double and a single quote, or begin or end with either: supervisord’s environment line has no escape character, so such a value is refused with 400 naming the variable, unless the program has a terminal_id, no port_range and a user other than root. A value with a double quote and no single quote is written in single quotes, any other in double quotes. The stored map is not the whole process environment: with inject_container_env the program also receives PID 1’s environment (Kit programs only its HOODY_* variables in the default mode); without it, only the variables its command names. Explicit values override injected ones.
inject_container_envbooleanNoWhether the daemon adds the container’s environment (PID 1’s, read from /proc/1/environ) to the program’s. When absent: true for a Hoody Kit program (see hoody_kit), false for every other program. When true, the daemon’s injection mode applies: by default a Kit program gets only the HOODY_* variables and any other program all of them. When false, nothing from PID 1 is added, HOODY_* included, except the variables the program’s command names as $X, ${X} or %(ENV_X)s: each is resolved from the program’s environment, then PID 1, then (for $X and ${X} in a program without port_range) the daemon’s own environment, and only that variable is added. For a sandboxed program a named value that is not literal, or a loader name, is dropped. This controls the daemon’s own injection only: the program still inherits supervisord’s environment.
port_rangeobjectNoPort range for multi-instance programs. {start, end}. Each port in the range creates a separate instance. Must not overlap any other stored program’s range. end - start + 1 must not exceed 4096.
port_paramstringNoParameter name for passing port (e.g. --port, -p). Valid ONLY together with port_range; sending it on its own is rejected with "port_param requires port_range to be set". Has no schema default on purpose.
lazy_loadbooleanNoEnable lazy loading (autostart=false). When true, program/instances are NOT started automatically. Started on-demand by edge proxy. Default: false. Cannot be combined with boot: true.
ready_portintegerNoTCP readiness port, 1 to 65535. When set, a start with wait=true is reported successful only once supervisord reports the program running AND this port accepts a TCP connection. 0 is refused.
displaystring | integerNoHoody Display number for GUI programs, 1 to 40000 (display 0 is not accepted; only screen 0, so ":1" or ":1.0"). Accepts "1", ":1" or the number 1.
terminal_idintegerNoHoody Terminal integration: session ID, 1 to 65535. Must be unique among persistent programs. Cannot be combined with an effective sandbox, or with port_range (a port-range program has no terminal). The program runs as its user, root or not, and gets TERM=xterm-256color unless its environment sets TERM. When the command ends, the program ends with the command’s exit code, so its status and autorestart follow the command, and clients attached to its terminal are disconnected with WebSocket close code 4404 (daemon program ended); a restarted program is reached by attaching again. See Watching and driving a terminal program. In interactive mode that is when the shell left after the command ends, and with tmux when the tmux client does. Output the program writes while hoody-terminal has no connection to it waits in the terminal, up to about 19 KB, and a program that writes more blocks until something attaches; once anything has attached or used the terminal’s REST automation, hoody-terminal stays connected until the program ends or the terminal session is deleted. A stop ends everything the program runs in its terminal: TERM first, KILL after 7 s for whatever ignores it.
terminal_shellstringNoHoody Terminal integration: the shell that loads the environment, or tmux. A non-blank value requires terminal_id; the daemon accepts only an installed bash, zsh, fish, sh or tmux. With a shell, the command is one shell command line (pipes, && and variables work); without one, its words are passed as they are, with quotes grouping words and nothing expanded, and a # or ; after a space starts a comment, even inside quotes. Omit it, or send null, for direct execution. A blank string passes validation but is still used as a shell when terminal_id is set, which produces a broken command.
terminal_interactivebooleanNoHoody Terminal integration: override auto-detection of interactive vs service mode. true forces interactive (the command runs and the shell stays), false forces service (the shell loads its rc file and is replaced by the command when it is a single command; a list, pipe or leading assignment runs as written), undefined/null auto-detects.
webhooksobjectNoWebhook notification configuration. enabled and urls are REQUIRED whenever this object is present. At most 5 URLs when enabled is true.
sandboxobjectNoPer-program confinement. On add, absent and null are the same thing. A policy rejection is a 400. Among its fields: network.udp (allow or deny; deny refuses UDP, UDP-Lite, ICMP ping, SCTP and AF_RXRPC sockets and io_uring in every network mode, and makes glibc resolve names over TCP), process.max_cpu ("<n>%", 1 to 102400, where 100% is one CPU), process.max_file_size (largest single file, 1K to 1024G) and process.tmp_size (size of each private /tmp and /var/tmp, 1M to 64G; requires private_tmp: true and bubblewrap 0.10.0 or newer, reported by /health as bwrap_tmpfs_size). Each of them makes the block effective.

Response

Section titled “Response”
Terminal window
hoody daemon programs create \
  --name nodejs-app \
  --description "Production Node.js application" \
  --command "node server.js" \
  --user nodejs \
  --boot \
  --delay-seconds 10 \
  --autorestart unexpected \
  --directory /opt/myapp \
  --priority 100 \
  --environment NODE_ENV=production --environment PORT=3000 \
  --stdout-logfile /hoody/storage/hoody-daemon/logs/nodejs-app/stdout.log \
  --stderr-logfile /hoody/storage/hoody-daemon/logs/nodejs-app/stderr.log \
  -c "$CONTAINER_ID"

POST /api/v1/daemon/programs/edit/{id}

Section titled “POST /api/v1/daemon/programs/edit/{id}”

Updates an existing program. The path id identifies it; an id in the body is ignored. A top-level field that is omitted or null keeps its stored value (except sandbox, where null clears the block), and the create defaults do NOT apply (changing user alone does not recompute directory). Three fields are replaced as a unit rather than merged: environment replaces the whole map ({} clears it), port_range needs both start and end, and a webhooks object must carry enabled and urls. A partial port_range or webhooks object is a 400 naming the missing field. webhooks: null does not clear stored webhooks. Unknown top-level keys are ignored, except a near-miss of sandbox, which is a 400.

When it takes effect. An edit that leaves the program disabled removes its supervisord definition at once. An edit to an enabled program with boot, lazy_load, a port_range, or a current or former effective sandbox is applied before the call returns and can restart the running instance; an apply failure is a 400 after saving only when a sandbox is or was involved.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program. An id that is not a valid i32 (a word, an empty segment, a number too large) never reaches the handler: the path extractor refuses it with a plain-text 404, on every route that takes an id, which is NOT the documented JSON 404 of the routes that have one. An id that parses but names no program is the handler’s own answer, a 400 carrying the {success: false, error:...} envelope.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
namestringNoProgram name. Must be unique, start with a letter or digit, contain only letters, digits, ., - and _, up to 128 characters.
descriptionstringNoHuman-readable description.
commandstringNoCommand to execute with full arguments. Must not contain a line feed, carriage return or NUL.
userstringNoSystem user (must exist on the system). A Linux account name matched case-insensitively: starts with a letter or _, continues with letters, digits, _ and -, may end in $, at most 32 bytes.
enabledbooleanNoEnable the program immediately.
bootbooleanNoStart automatically on system boot.
delay_secondsintegerNoSeconds the program must STAY RUNNING for supervisord to consider the start successful (supervisord’s startsecs). The program is launched immediately. 0 does NOT disable the window: the daemon writes startsecs=1 at 0. Under autorestart "unexpected" or "true", a non-zero exit or a signal inside the window is a failed start, retried up to startretries times and then fatal. An end that is not a crash under autorestart (any end under "false", an exit 0 otherwise) is not a failed start, however quick: it is kept from supervisord until the window has passed, so a one-shot runs once. Under "false" and "unexpected" it is reported as exited as soon as it ends, with its exit code or signal in last_run; under "true" it is started again once the window has passed. A stop, edit or removal sent in that window can take up to this long to return. Hoody Kit programs keep supervisord’s own rule: any exit inside the window is a failed start, whatever autorestart says.
autorestartstring | booleanNoRestart policy: "unexpected", "true", "false", or booleans. A program that exits on its own under "false", or with exit 0 under "unexpected", has finished and is reported as exited with its result in last_run, however quickly it exits; a non-zero exit or a signal inside the delay_seconds window under "unexpected" or "true" is a failed start. Omitted or null, the stored policy is kept.
directorystringNoWorking directory: an absolute path of ASCII letters and digits, /, _, ., -, space and tab, with no .. path component, that must exist. Omitted, the stored directory is kept, even when user changes.
priorityintegerNoStart priority, lower starts first. Any u32 is accepted; no range is enforced.
stdout_logfilestringNoPath for standard output log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Omitted or null, the stored path is kept.
stderr_logfilestringNoPath for standard error log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Omitted or null, the stored path is kept.
logs_enabledbooleanNoWhether logging is enabled. Omitted, the stored value is kept.
log_max_bytesintegerNoMaximum size of each log file in bytes before rotation. Omitted, the stored value is kept.
log_backupsintegerNoNumber of rotated backup log files to keep. Omitted, the stored value is kept.
environmentobjectNoEnvironment variables as key-value pairs. On edit the map REPLACES the stored one: resend every variable you want kept; {} clears it. A value may not hold both a double and a single quote, or begin or end with either: supervisord’s environment line has no escape character, so such a value is refused with 400 naming the variable, unless the program has a terminal_id, no port_range and a user other than root. A value with a double quote and no single quote is written in single quotes, any other in double quotes. The stored map is not the whole process environment: with inject_container_env the program also receives PID 1’s environment (Kit programs only its HOODY_* variables in the default mode); without it, only the variables its command names. Explicit values override injected ones.
inject_container_envbooleanNoWhether the daemon adds the container’s environment (PID 1’s, read from /proc/1/environ) to the program’s. When absent: true for a Hoody Kit program (see hoody_kit), false for every other program. When true, the daemon’s injection mode applies: by default a Kit program gets only the HOODY_* variables and any other program all of them. When false, nothing from PID 1 is added, HOODY_* included, except the variables the program’s command names as $X, ${X} or %(ENV_X)s: each is resolved from the program’s environment, then PID 1, then (for $X and ${X} in a program without port_range) the daemon’s own environment, and only that variable is added. For a sandboxed program a named value that is not literal, or a loader name, is dropped. This controls the daemon’s own injection only: the program still inherits supervisord’s environment. On edit: absent leaves the stored value unchanged and there is no null; to return to the derived default, send the value it derives (true for a Hoody Kit program, false otherwise).
port_rangeobjectNoPort range for multi-instance programs. Replaces the stored range; needs both start and end. Must not overlap any other stored program’s range. end - start + 1 must not exceed 4096.
port_paramstringNoParameter name for passing port. Valid ONLY together with port_range; sending it on its own is rejected with "port_param requires port_range to be set".
lazy_loadbooleanNoEnable lazy loading (autostart=false). Cannot be combined with boot: true.
ready_portintegerNoTCP readiness port, 1 to 65535. When set, a start with wait=true succeeds only once supervisord reports running AND this port accepts a TCP connection. 0 is refused.
displaystring | integerNoHoody Display number for GUI programs, 1 to 40000 (display 0 is not accepted; only screen 0, so ":1" or ":1.0"). Accepts "1", ":1" or the number 1.
terminal_idintegerNoHoody Terminal integration: session ID, 1 to 65535. Must be unique among persistent programs. Cannot be combined with an effective sandbox, or with port_range (a port-range program has no terminal). The program runs as its user, root or not, and gets TERM=xterm-256color unless its environment sets TERM. When the command ends, the program ends with the command’s exit code, so its status and autorestart follow the command, and clients attached to its terminal are disconnected with WebSocket close code 4404 (daemon program ended); a restarted program is reached by attaching again. See Watching and driving a terminal program. In interactive mode that is when the shell left after the command ends, and with tmux when the tmux client does. Output the program writes while hoody-terminal has no connection to it waits in the terminal, up to about 19 KB, and a program that writes more blocks until something attaches; once anything has attached or used the terminal’s REST automation, hoody-terminal stays connected until the program ends or the terminal session is deleted. A stop ends everything the program runs in its terminal: TERM first, KILL after 7 s for whatever ignores it.
terminal_shellstringNoHoody Terminal integration: the shell that loads the environment, or tmux. A non-blank value requires terminal_id; the daemon accepts only an installed bash, zsh, fish, sh or tmux. With a shell, the command is one shell command line (pipes, && and variables work); without one, its words are passed as they are, with quotes grouping words and nothing expanded, and a # or ; after a space starts a comment, even inside quotes. Omit it, or send null, for direct execution. A blank string passes validation but is still used as a shell when terminal_id is set, which produces a broken command. Omitted or null on edit, the stored shell is kept.
terminal_interactivebooleanNoHoody Terminal integration: override auto-detection of interactive vs service mode.
webhooksobjectNoWebhook notification configuration. enabled and urls are REQUIRED whenever this object is present. On edit the two are replaced rather than merged. webhooks: null does not clear stored webhooks.
sandboxobject | nullNoPer-program confinement. Three-state: absent leaves the current block unchanged, null clears it, and an object REPLACES it as a unit (no field-level merge). Accepts the same network.udp, process.max_cpu, process.max_file_size and process.tmp_size fields as on add.

Response

Section titled “Response”
Terminal window
hoody daemon programs update 1 \
  --description "Updated description" \
  --command "node server.js --production" \
  --environment NODE_ENV=production --environment PORT=8080 \
  -c "$CONTAINER_ID"

POST /api/v1/daemon/programs/remove/{id}

Section titled “POST /api/v1/daemon/programs/remove/{id}”

Permanently deletes a program from the configuration. The program row is deleted FIRST, and only then is its supervisord configuration withdrawn: what stops a running process is the reload that covers that withdrawal, not a stop issued beforehand. A withdrawal that cannot be confirmed answers 400 with the row already gone, says so, and leaves the configuration for the orphan sweep at the next daemon start. This is a destructive operation that cannot be undone.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program. An id that is not a valid i32 never reaches the handler: the path extractor refuses it with a plain-text 404. An id that parses but names no program is the handler’s own answer, a 400 carrying the {success: false, error:...} envelope.

Response

Section titled “Response”
Terminal window
hoody daemon programs delete 1 -c "$CONTAINER_ID"

POST /api/v1/daemon/programs/reset

Section titled “POST /api/v1/daemon/programs/reset”

Replaces the current programs.json with the initial default snapshot (programs.default.json) created at container setup time. Removes every managed program’s supervisord configuration, asks supervisord to reload, and applies the default boot programs. The reload is what stops the old processes, and its failure is logged rather than returned: a 200 means the defaults were persisted and applied, not that every earlier process is gone. Use this when programs have been misconfigured and a clean slate is needed.

Response

Section titled “Response”
Terminal window
hoody daemon programs reset -c "$CONTAINER_ID"

Lazy loading

Section titled “Lazy loading”

lazy_load: true (boolean, default false) means the program does not start on its own, at boot or otherwise. It stays registered and costs nothing until something asks for it. The mechanism differs by program shape:

  • For a program WITH port_range, lazy_load explicitly renders autostart=false and every port in the range becomes its own registered-but-not-running instance. This is the form the edge proxy activates.
  • For a program WITHOUT port_range, supervisord’s autostart simply follows boot, and the API’s rejection of lazy_load: true + boot: true is what forces it false. The standard renderer never reads lazy_load.

A program with lazy_load: true and NO port_range is also not applied to supervisord on create at all; apply happens only when port_range is set or boot is true. Every lazy Kit service is registered with a single-port range ({start: p, end: p}) for exactly this reason.

Who starts it

Section titled “Who starts it”

The Hoody Proxy starts lazy programs on the first request that routes to the program’s port. The proxy resolves the port from the hostname, then asks the daemon GET /api/v1/daemon/programs?lazy_load=true&port={port}&include_status=true. If a matching enabled program is not RUNNING, the proxy calls POST /api/v1/daemon/programs/{id}/start with { "if_not_running": true, "wait": true, "timeout": 30 } (plus "port" for a port-range program) and HOLDS the client request until the process reaches RUNNING, then proxies it. The caller sees one slow request, not an error.

Later requests hit a short per-port cache and pay nothing. The first request may wait while the program starts (up to about 30 seconds by default); later requests go straight through.

A first-request example

Section titled “A first-request example”
  1. The user opens https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com.
  2. Nothing is listening yet, because hoody-notes is registered lazy_load: true.
  3. The proxy queries GET /api/v1/daemon/programs?lazy_load=true&port=8042&include_status=true, finds the program not running, and calls POST /api/v1/daemon/programs/{id}/start with { "if_not_running": true, "wait": true, "timeout": 30, "port": 8042 }.
  4. The request completes normally once the process is up, having been held for the startup.

Scope

Section titled “Scope”

The daemon lookup is purely by port (?lazy_load=true&port=N); it names no service, and the activation cache is keyed on containerIp:port. The hostname’s SERVICE LABEL decides only WHETHER the proxy runs the activation step, not how the daemon is queried. A http-<port> hostname does NOT trigger activation unless <port> is the port of an ENABLED SERVICE IN THE PROXY’S SERVICE REGISTRY (not merely a “Kit service”; the registry includes non-Kit entries such as daemon); the http- form otherwise yields no service name. The request still routes; it just reaches whatever is already listening. Start such an instance with POST /programs/{id}/start ({ "port": <port> } for a port-range program).

Shipped Kit programs

Section titled “Shipped Kit programs”

The Kit programs registered lazy_load: true (13) are: hoody-browser, hoody-code, hoody-curl, hoody-display, hoody-exec, hoody-files, hoody-notes, hoody-notifications, hoody-pipe, hoody-run, hoody-sqlite, hoody-tunnel, hoody-workspaces.

Registered EAGERLY, NOT lazy (5): hoody-agent, hoody-cron, hoody-egress, hoody-watch, and hoody-terminal (where the terminal kit is enabled; it is registered with boot: true and a port_range but no lazy_load).

That is 18 Kit programs in total, 13 lazy. This is how most of the Kit behaves already: a container is not running fourteen daemons, it is running the ones someone has actually opened.

Quick Start

Section titled “Quick Start”

POST /api/v1/daemon/quick-start

Section titled “POST /api/v1/daemon/quick-start”

Creates and starts a temporary custom program. Custom programs only; system services (apache2, nginx, etc.) belong under systemctl.

Key features:

  • Not saved to programs.json (temporary only); tracked in ephemeral.json with its result, so it survives a daemon restart
  • Always created with autostart=false (does not auto-start on reboot)
  • Lifetime: an optional ttl bounds the whole execution from launch, across retries and restarts; expires_at is that deadline. When it passes the program is stopped and last_run.error reads ttl expired (checked every 10 seconds, so not exact).
  • Results: once the program finishes (exited with no restart to follow, fatal, or stopped through the stop endpoint) its definition is withdrawn and its status, last_run and logs stay readable for 10 minutes; then status and logs answer 404. Log files are never deleted.
  • Daemon restart: a program that finished while the daemon was down keeps the exit code supervisord recorded; one still running is stopped and its last_run.error reads daemon restarted before the program finished.
  • The returned temporary_id has the form quick_<milliseconds>_<sequence>; it is not a numeric program id. Every response after creation carries it, errors included.
  • wait: true returns when the command finishes (200, status: "exited" and last_run, whatever the exit code) or when a long-running program is running. A wait that times out does not cancel the launch. A start whose reply was lost answers 502 and is never retried.
  • Runs once by default: autorestart defaults to "false" here (persistent programs default to "unexpected"), so a failing command is not run again. Set autorestart to have it restarted.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
commandstringYesCommand to execute with full arguments. Must not contain a line feed, carriage return or NUL.
userstringYesSystem user to run as (must exist on the system). A Linux account name matched case-insensitively: starts with a letter or _, continues with letters, digits, _ and -, may end in $, at most 32 bytes. Quick-start programs cannot be sandboxed.
namestringNoCustom name (auto-generated if omitted). Starts with a letter or digit, contains only letters, digits, ., - and _, up to 128 characters.
autorestartstring | booleanNoRestart policy: "false" (default for a quick-start) never restarts; "unexpected" restarts after an exit code other than 0; "true" always; booleans are accepted too. Omitted, a quick-start runs once: any end, whatever its exit code or signal, is reported as exited with the code or signal in last_run (with wait: true, a 200), and a command that cannot be executed fails once and is not retried. A quick-start that should be restarted after a crash, such as a temporary server, sets "unexpected" or "true". Persistent programs keep "unexpected" as their default. A program that exits on its own under "false", or with exit 0 under "unexpected", has finished, however quickly it exits: it is reported as exited with its result in last_run and runs once. Under "unexpected" and "true" a non-zero exit or a signal inside the delay_seconds window is a failed start, retried up to startretries times and then fatal.
directorystringNoWorking directory: an absolute path of ASCII letters and digits, /, _, ., -, space and tab, with no .. path component, that must exist. Defaults to the user’s home directory, or /tmp.
environmentobjectNoEnvironment variables as key-value pairs. A value may not hold both a double and a single quote, or begin or end with either: supervisord’s environment line has no escape character, so such a value is refused with 400 naming the variable, unless the program has a terminal_id, no port_range and a user other than root. A value with a double quote and no single quote is written in single quotes, any other in double quotes. The stored map is not the whole process environment: with inject_container_env: true the program also receives PID 1’s environment; without it, only the variables its command names. Explicit values override injected ones.
inject_container_envbooleanNoWhether the daemon adds the container’s environment (PID 1’s) to the program’s. Absent means false for a quick-start, whatever its directory. When true, the daemon’s injection mode applies (all variables by default). When false, nothing from PID 1 is added except the variables the command names as $X, ${X} or %(ENV_X)s, resolved from environment, then PID 1, then (for $X and ${X}) the daemon’s own environment. The program still inherits supervisord’s environment.
priorityintegerNoStart priority, lower starts first. Default: 999.
delay_secondsintegerNoSeconds the program must STAY RUNNING for supervisord to consider the start successful. 0 does NOT disable the window: the daemon writes startsecs=1 at 0. A finished run that is not a crash under autorestart is kept from supervisord until the window has passed, so a one-shot runs once.
stdout_logfilestringNoPath for standard output log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Defaults to /hoody/storage/hoody-daemon/logs/<name>/stdout.log.
stderr_logfilestringNoPath for standard error log. Must be under /hoody/storage/hoody-daemon/logs; any other path is a 400. Defaults to /hoody/storage/hoody-daemon/logs/<name>/stderr.log.
logs_enabledbooleanNoWhether logging is enabled. Default: true.
log_max_bytesintegerNoMaximum size of each log file in bytes before rotation. Default: 5242880 (5MB).
log_backupsintegerNoNumber of rotated backup log files to keep. Default: 2.
ttlintegerNoTime-to-live in seconds, counted from launch (when the daemon dispatches the start) and bounding the whole execution, across retries and restarts. The deadline is returned as expires_at. Expiry is checked every 10 seconds, so it is not an exact deadline; 0 expires at the first check. A very large value means no practical expiry.
waitbooleanNoWait for the program to reach RUNNING state before returning. A command that finishes during the wait answers 200 with status: "exited" and its last_run, whatever the exit code. Default: false.
timeoutintegerNoSeconds to wait for the program to be running when wait=true. Default: 30. The server clamps it to 300.
displaystring | integerNoHoody Display number for GUI programs, 1 to 40000 (display 0 is not accepted; only screen 0, so ":1" or ":1.0"). Accepts "1", ":1" or the number 1.
terminal_idintegerNoHoody Terminal integration: session id, 0 to 65535. Quick-start does not check it for uniqueness. The program runs as its user, root or not, and gets TERM=xterm-256color unless its environment sets TERM. When the command ends, the program ends with the command’s exit code, so its status and autorestart follow the command, and clients attached to its terminal are disconnected with WebSocket close code 4404 (daemon program ended); a restarted program is reached by attaching again. See Watching and driving a terminal program. In interactive mode that is when the shell left after the command ends, and with tmux when the tmux client does. Output the program writes while hoody-terminal has no connection to it waits in the terminal, up to about 19 KB, and a program that writes more blocks until something attaches; once anything has attached or used the terminal’s REST automation, hoody-terminal stays connected until the program ends or the terminal session is deleted. A stop ends everything the program runs in its terminal: TERM first, KILL after 7 s for whatever ignores it.
terminal_shellstringNoHoody Terminal integration: shell wrapper for environment loading. Quick-start does not validate the name or check that the shell is installed, and a shell without terminal_id is ignored. A blank string passes validation but is still used as a shell when terminal_id is set, which produces a broken command. Omit it, or send null, for direct execution.
terminal_interactivebooleanNoHoody Terminal integration: override auto-detection.

Response

Section titled “Response”
Terminal window
QUICK_ID=$(hoody -o json daemon ephemeral programs start \
  --command "node test-server.js" --user nodejs \
  --name temp-test-server --directory /opt/test --ttl 1800 \
  --environment PORT=9999 --environment NODE_ENV=test \
  --wait -c "$CONTAINER_ID" | jq -r '.temporary_id')
hoody -o json daemon ephemeral programs status "$QUICK_ID" -c "$CONTAINER_ID"

GET /api/v1/daemon/quick-start

Section titled “GET /api/v1/daemon/quick-start”

Returns all currently tracked ephemeral programs with their current runtime status. An ephemeral program’s supervisord definition is withdrawn once it finishes, is stopped or expires; its entry (status, last_run) stays in this list for 10 minutes after that, and its log files are never deleted. Each entry may carry last_run (the result of its last ended run) and supervisor_state (only when supervisord’s own state differs from status); status can also read failed when the definition never loaded. expires_at is the absolute execution deadline, the launch time plus ttl.

This endpoint takes no parameters.

Response

Section titled “Response”
Terminal window
hoody daemon ephemeral programs list -c "$CONTAINER_ID"

GET /api/v1/daemon/quick-start/{id}/status

Section titled “GET /api/v1/daemon/quick-start/{id}/status”

Retrieves the current runtime status for a specific ephemeral program by its temporary_id. A finished program answers the status it finished with (exited, fatal, stopped, or failed when its definition never loaded) and its last_run for 10 minutes after it finished, then 404. The response has the same shape as the quick-start response: only success is guaranteed.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTemporary ID of the ephemeral program, as returned in temporary_id: quick_<unix-ms>_<sequence>.

Response

Section titled “Response”
Terminal window
hoody daemon ephemeral programs status "$QUICK_ID" -c "$CONTAINER_ID"

GET /api/v1/daemon/quick-start/{id}/logs

Section titled “GET /api/v1/daemon/quick-start/{id}/logs”

Retrieves the last N lines from an ephemeral program’s stdout or stderr log file. For a file over 10 MiB, reading starts 10 MiB before the end, so fewer lines can come back and the first can be partial. A log path outside the log root, and a missing, unreadable or non-UTF-8 file, are 400s even for an existing id; a file error carries type and log_file too. A malformed lines value is refused as plain text. Default ephemeral log paths are keyed on the program NAME: /hoody/storage/hoody-daemon/logs/<name>/stdout.log.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesEphemeral program temporary ID (temporary_id).
typequerystringNoLog stream: stdout or stderr. Default: stdout.
linesqueryintegerNoNumber of lines to return from the end of the file. Default 100; 0 returns empty content and a larger value is clamped to 10000 rather than refused.

Response

Section titled “Response”
Terminal window
hoody daemon ephemeral programs logs get "$QUICK_ID" --type stdout --lines 50 -c "$CONTAINER_ID"

POST /api/v1/daemon/quick-start/{id}/stop

Section titled “POST /api/v1/daemon/quick-start/{id}/stop”

Stops the program, records its result and withdraws its supervisord configuration. The entry is KEPT: its status, last_run and logs stay readable for 10 minutes after it finished, and its log files are never deleted. To run the same command again, create a new ephemeral program.

The daemon asks supervisord to stop the program (a stop that is not confirmed is logged and does not end the request), records the result with status: "stopped" (the run’s own report when there is one, otherwise what supervisord recorded), then removes the group from supervisord and deletes its config file. cleaned_up: true means that withdrawal was CONFIRMED. cleaned_up: false means the result is recorded but the withdrawal is still owed; it is retried in the background and at the next daemon start before the entry is ever dropped. Either way the answer is 200. Once the withdrawal is confirmed the program cannot start again; while it is still owed and the stop itself was not confirmed, supervisord may still restart the program under its autorestart policy until a retry completes the withdrawal.

Stopping a program that already finished changes nothing about its result and answers 200; an id that is unknown, or whose retention has ended, is a 404.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesTemporary ID of the ephemeral program to stop (temporary_id).

Response

Section titled “Response”
Terminal window
hoody daemon ephemeral programs stop "$QUICK_ID" -c "$CONTAINER_ID"