Skip to content
Hoody.com

The terminal service exposes endpoints for inspecting the runtime state of a container instance (CPU, memory, processes, network ports, displays, and daemons) and for actively managing it: sending signals to processes, freezing/resuming workloads, and controlling system power. Use these endpoints to power dashboards, automate cleanup, or correlate resource pressure with running workloads.

All endpoints on this page are scoped to a single container instance. The base URL targets one terminal replica; replace {projectId}, {containerId}, and {server} with values from your environment.

Liveness probe for the terminal service. Returns the standardized 9-field health envelope. Unauthenticated. Always returns HTTP 200 with application/json when the service is responsive.

This endpoint takes no parameters.

Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/terminal/health"

Returns comprehensive system statistics: CPU usage (per-core and aggregate), memory, swap, network interfaces, uptime, and disk usage.

This endpoint takes no parameters.

Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/resources"

Returns information about connected displays, sourced from the host’s external display script. Useful for graphics-aware tooling and remote-desktop dashboards.

This endpoint takes no parameters.

Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/displays"

Returns the JSON array of daemon programs from the hoody-daemon configuration. Use this to discover long-running background services available on the instance.

This endpoint takes no parameters.

Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/daemon"

Returns the array of all running processes, with CPU, memory, and state information. Supports sorting, filtering by name (case-insensitive substring), and limiting result count.

NameInTypeRequiredDescription
sortquerystringNoSort by field. One of cpu, memory, pid, name. Default: pid.
limitqueryintegerNoMaximum number of processes to return. Default: all.
filterquerystringNoFilter by process name (substring match, case-insensitive).
Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/processes?sort=cpu&limit=20&filter=node"

Returns detailed information about a specific process: full stats, command line, environment variables, and open files.

NameInTypeRequiredDescription
pidpathintegerYesProcess ID.
Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/processes/1024"

Send a Unix signal to one or more processes. Target by pid (single process) or by name (signals every matching process — case-insensitive comm match, truncated to 15 characters). Supports all standard signals including SIGTERM, SIGKILL, SIGSTOP, SIGCONT, and realtime signals (32..64 on Linux). Pass the signal as a string (SIGTERM, TERM, 15) or as an integer.

FieldTypeRequiredDescription
pidintegerNoProcess ID to signal. Mutually exclusive with name.
namestringNoProcess name to signal — signals ALL matching processes. Mutually exclusive with pid.
signalstring or integerNoSignal to send. String form accepts SIGTERM, TERM, 15, etc. (with or without SIG prefix). Integer form accepts any value in [0, NSIG), including realtime signals SIGRTMIN..SIGRTMAX (typically 34..64 on Linux), which have no portable string names.
forcebooleanNoShorthand for SIGKILL (true) or SIGTERM (false) — overrides the signal parameter.
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/process/signal" \
-H "Content-Type: application/json" \
-d '{"pid": 1024, "signal": "SIGTERM"}'

SIGSTOP suspends a process’s entire thread group; SIGCONT resumes it. These endpoints let you pause background workloads (builds, fine-tunes, AI inference) without losing in-memory state, then resume them later.

Target by pid (a single process) or by name (every process whose comm matches case-insensitively). Linux truncates comm to 15 characters; a longer name silently matches nothing. Set include_descendants: true to fan out across the target’s child processes via a one-shot /proc PPID snapshot bounded at 65535 PIDs; the parent is signalled first so a forked child cannot escape, but the operation is best-effort and not atomic. By-name descendant traversal dedupes overlapping subtrees.

Suspend execution by delivering SIGSTOP to the target process or process tree. Resumed by a matching call to POST /api/v1/system/processes/unfreeze.

FieldTypeRequiredDescription
pidintegerNoProcess ID to freeze. Mutually exclusive with name. PIDs 1, 2, the server’s own PID, and the server’s parent PID are guarded and return 403.
namestringNoProcess name (case-insensitive comm match; freezes EVERY matching process). Mutually exclusive with pid. Truncated to 15 characters by Linux.
include_descendantsbooleanNoWhen true, also freezes every descendant via a /proc PPID snapshot (bounded at 65535 PIDs). Default false.
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/processes/freeze" \
-H "Content-Type: application/json" \
-d '{"pid": 1024, "include_descendants": true}'

Resume execution by delivering SIGCONT. The body schema mirrors /freeze exactly — same pid/name selector and include_descendants option. Calling unfreeze on a process that is already running is harmless: SIGCONT is a no-op for non-stopped processes.

FieldTypeRequiredDescription
pidintegerNoProcess ID to unfreeze. Mutually exclusive with name. The guarded-PID set (1, 2, self, parent) returns 403.
namestringNoProcess name (case-insensitive comm match). Mutually exclusive with pid. Truncated to 15 characters by Linux.
include_descendantsbooleanNoAlso unfreeze all descendants via a /proc PPID snapshot (bounded at 65535 PIDs). Default false. By-name traversal dedupes overlapping subtrees.
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/processes/unfreeze" \
-H "Content-Type: application/json" \
-d '{"pid": 1024, "include_descendants": true}'

Returns all listening TCP/UDP ports with owning process information. Supports extensive filtering so you can narrow the result to a specific protocol, user, port, or IP range.

NameInTypeRequiredDescription
protocolquerystringNoFilter by protocol: tcp, udp, or a comma-separated list.
userquerystringNoFilter by user (exact match).
portqueryintegerNoFilter by specific port number.
ipquerystringNoFilter by IP address (comma-separated list).
skip_programquerystringNoExclude specific programs (comma-separated list).
http_onlyquerybooleanNoOnly return HTTP services.
hoody_onlyquerybooleanNoOnly return Hoody Kit services.
Terminal window
curl -X GET "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/ports?protocol=tcp&http_only=true"

Both endpoints schedule via shutdown(8), which only schedules in whole minutes — sub-minute delays are rounded up. The actual scheduled delay is reported in the response as effective_minutes. Both require root/sudo; the Linux kernel enforces permission checks.

Initiate a system reboot. Optionally delay the action by up to 24 hours.

NameInTypeRequiredDescription
delayqueryintegerNoDelay in seconds before reboot, in the range 0..86400 (default 0 for immediate). The server rounds up to the nearest minute and reports effective_minutes in the response.
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/reboot?delay=60"

Initiate a system shutdown. Optionally delay the action by up to 24 hours.

NameInTypeRequiredDescription
delayqueryintegerNoDelay in seconds before shutdown, in the range 0..86400 (default 0 for immediate). The server rounds up to the nearest minute and reports effective_minutes in the response.
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/system/shutdown?delay=300"

A terminal client posts its own render/connection health here so the server can correlate client-side stalls (frozen UI, dropped WebSocket, WebGL fallback) with server-side session state.

Post a client-state envelope for diagnostics correlation. The request body is optional; if omitted, the server just records that the client reached the endpoint.

FieldTypeRequiredDescription
build_idstringNoFrontend build identifier.
rendererstringNoEffective renderer, typically webgl or dom.
reasonstringNoWhat triggered this beacon (for example, connection_resumed, render_stall).
Terminal window
curl -X POST "https://{projectId}-{containerId}-terminal-1.{server}.containers.hoody.com/api/v1/terminal/state" \
-H "Content-Type: application/json" \
-d '{"build_id": "web-1.4.2", "renderer": "webgl", "reason": "connection_resumed"}'