Terminal: System Monitoring

Overview

The Terminal System Monitoring service exposes endpoints to inspect and control the host running the Hoody daemon. Use it to build process inspectors, port scanners, system dashboards, and lifecycle automation. Operations cover system resources, daemon configuration, displays, listening ports, process introspection, signal delivery, process freeze/unfreeze, and full system power management.

All endpoints are served under /api/v1/system/... except the health probe, which lives at /api/v1/terminal/health.

Health Check

`GET /api/v1/terminal/health`

Returns the standardized 9-field health response. Unauthenticated. Always returns HTTP 200 with application/json when the service is up.

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/terminal/health

const health = await client.terminal.health.check();

{
  "status": "ok",
  "service": "terminal",
  "uptime_seconds": 38421,
  "version": "1.4.2",
  "timestamp": "2025-01-15T14:22:08Z",
  "host": "hoody-prod-01",
  "cpu_percent": 12.4,
  "memory_percent": 41.7,
  "load_average": [0.42, 0.51, 0.48]
}

System Resources

`GET /api/v1/system/resources`

Returns comprehensive system statistics including CPU usage, memory, network interfaces, uptime, and disk usage.

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/system/resources \
  -H "Authorization: Bearer <token>"

const stats = await client.terminal.system.getResources();

{
  "cpu": {
    "percent": 14.2,
    "cores": 8,
    "load_average": [0.42, 0.51, 0.48]
  },
  "memory": {
    "total_bytes": 16777216000,
    "used_bytes": 7011696640,
    "free_bytes": 9765519360,
    "percent": 41.8
  },
  "uptime_seconds": 38421,
  "hostname": "hoody-prod-01",
  "network": [
    {
      "interface": "eth0",
      "rx_bytes": 4829301248,
      "tx_bytes": 1823745024
    }
  ],
  "disks": [
    {
      "mount": "/",
      "total_bytes": 536870912000,
      "used_bytes": 214748364800,
      "free_bytes": 322122547200,
      "percent": 40.0
    }
  ]
}

Daemon Configuration

`GET /api/v1/system/daemon`

Returns the JSON array of daemon programs from the hoody-daemon config.

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/system/daemon \
  -H "Authorization: Bearer <token>"

const daemons = await client.terminal.system.getDaemonConfig();

[
  {
    "name": "hoody-supervisor",
    "command": "/usr/local/bin/hoody-supervisor",
    "auto_start": true,
    "restart_policy": "on-failure"
  },
  {
    "name": "hoody-watcher",
    "command": "/usr/local/bin/hoody-watcher",
    "auto_start": true,
    "restart_policy": "always"
  }
]

Display Information

`GET /api/v1/system/displays`

Returns information about connected displays from the external display script.

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/system/displays \
  -H "Authorization: Bearer <token>"

const displays = await client.terminal.system.getDisplayInfo();

[
  {
    "name": "eDP-1",
    "connected": true,
    "resolution": "2560x1440",
    "scale": 2.0,
    "is_internal": true
  },
  {
    "name": "HDMI-1",
    "connected": false,
    "resolution": null,
    "scale": 1.0,
    "is_internal": false
  }
]

Network Ports

`GET /api/v1/system/ports`

Returns a JSON array of all TCP/UDP listening ports with associated process information. Supports extensive filtering on protocol, user, port, IP, program name, and HTTP/Hoody-Kit service detection.

Parameters

Name	In	Type	Required	Description
`protocol`	query	string	No	Filter by protocol: `tcp`, `udp`, or comma-separated list
`user`	query	string	No	Filter by user (exact match)
`port`	query	integer	No	Filter by specific port number
`ip`	query	string	No	Filter by IP address (comma-separated list)
`skip_program`	query	string	No	Exclude specific programs (comma-separated list)
`http_only`	query	boolean	No	Only return HTTP services
`hoody_only`	query	boolean	No	Only return Hoody Kit services

curl -X GET "https://api.hoody.com/api/v1/system/ports?protocol=tcp&user=root&http_only=true" \
  -H "Authorization: Bearer <token>"

for await (const port of client.terminal.system.listPortsIterator({
  protocol: "tcp",
  user: "root",
  http_only: true
})) {
  // ...
}

[
  {
    "protocol": "tcp",
    "address": "0.0.0.0",
    "port": 22,
    "pid": 891,
    "program": "sshd",
    "user": "root",
    "is_http": false,
    "is_hoody": false
  },
  {
    "protocol": "tcp",
    "address": "127.0.0.1",
    "port": 8080,
    "pid": 4127,
    "program": "hoody-server",
    "user": "hoody",
    "is_http": true,
    "is_hoody": true
  }
]

Processes

`GET /api/v1/system/processes`

Returns a JSON array of all processes with CPU, memory, and state information. Supports sorting, filtering, and limiting.

Parameters

Name	In	Type	Required	Description
`sort`	query	string	No	Sort by field. Allowed values: `cpu`, `memory`, `pid`, `name`. Default: `pid`
`limit`	query	integer	No	Maximum number of processes to return. Default: all
`filter`	query	string	No	Filter by process name (substring match, case-insensitive)

curl -X GET "https://api.hoody.com/api/v1/system/processes?sort=cpu&limit=10" \
  -H "Authorization: Bearer <token>"

for await (const proc of client.terminal.system.listProcessesIterator({
  sort: "cpu",
  limit: 10
})) {
  // ...
}

[
  {
    "pid": 4127,
    "name": "hoody-server",
    "user": "hoody",
    "cpu_percent": 38.4,
    "memory_percent": 12.1,
    "memory_bytes": 2030043136,
    "state": "S",
    "command": "/usr/local/bin/hoody-server --config /etc/hoody/server.yml"
  },
  {
    "pid": 1892,
    "name": "python3",
    "user": "hoody",
    "cpu_percent": 21.7,
    "memory_percent": 4.2,
    "memory_bytes": 704643072,
    "state": "S",
    "command": "python3 /opt/hoody/inference/worker.py"
  }
]

`GET /api/v1/system/processes/{pid}`

Returns detailed information about a specific process including all stats, command line, environment, and open files.

Parameters

Name	In	Type	Required	Description
`pid`	path	integer	Yes	Process ID

curl -X GET https://api.hoody.com/api/v1/system/processes/4127 \
  -H "Authorization: Bearer <token>"

const proc = await client.terminal.system.getProcess({ pid: 4127 });

{
  "pid": 4127,
  "name": "hoody-server",
  "user": "hoody",
  "state": "S",
  "ppid": 1,
  "cpu_percent": 38.4,
  "memory_bytes": 2030043136,
  "threads": 12,
  "start_time": "2025-01-14T03:11:42Z",
  "cmdline": ["/usr/local/bin/hoody-server", "--config", "/etc/hoody/server.yml"],
  "environ": {
    "PATH": "/usr/local/bin:/usr/bin:/bin",
    "HOODY_HOME": "/var/lib/hoody"
  },
  "open_files": [
    "/etc/hoody/server.yml",
    "/var/log/hoody/server.log"
  ]
}

{
  "statusCode": 404,
  "error": "PROCESS_NOT_FOUND",
  "message": "No process with PID 99999"
}

Error Code	Title	Description	Resolution
`PROCESS_NOT_FOUND`	Process does not exist	Check PID is valid and process is running	Check PID is valid and process is running

Process Signals

`POST /api/v1/system/process/signal`

Send a Unix signal to one or more processes by PID or name. Supports all standard signals (SIGTERM, SIGKILL, SIGSTOP, SIGCONT, etc.). When targeting by name, the signal is delivered to every matching process.

Request Body

Field	Type	Required	Description
`pid`	integer	No	Process ID to signal. Mutually exclusive with `name`
`name`	string	No	Process name to signal — signals ALL matching processes. Mutually exclusive with `pid`
`signal`	string \| integer	No	Signal 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
`force`	boolean	No	Shorthand for `SIGKILL` (true) or `SIGTERM` (false). Overrides the `signal` parameter

You must supply either pid or name (not both) and either signal or force.

curl -X POST https://api.hoody.com/api/v1/system/process/signal \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 4127,
    "signal": "SIGTERM"
  }'

await client.terminal.system.sendSignal({
  data: {
    pid: 4127,
    signal: "SIGTERM"
  }
});

{
  "delivered": 1,
  "signal": "SIGTERM",
  "targets": [4127]
}

{
  "statusCode": 400,
  "error": "MISSING_TARGET",
  "message": "Must specify pid or name"
}

Error Code	Title	Description	Resolution
`MISSING_TARGET`	Must specify pid or name	Provide either pid or name parameter	Provide either pid or name parameter
`INVALID_SIGNAL`	Invalid signal name	Use valid signal (SIGTERM, SIGKILL, etc.)	Use valid signal (SIGTERM, SIGKILL, etc.)

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "message": "No permission to signal process"
}

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	No permission to signal process	Check process ownership	Check process ownership

{
  "statusCode": 405,
  "error": "method_not_allowed",
  "message": "POST required"
}

{
  "statusCode": 500,
  "error": "SIGNAL_FAILED",
  "message": "Failed to send signal"
}

Error Code	Title	Description	Resolution
`SIGNAL_FAILED`	Failed to send signal	Check process exists	Check process exists

Process Freeze / Unfreeze

The freeze and unfreeze endpoints let you suspend and resume processes (or whole process trees) without losing in-memory state. They are useful for pausing background workloads such as builds, fine-tunes, or AI inference.

`POST /api/v1/system/processes/freeze`

Suspend execution of one or more processes by delivering SIGSTOP. Pair this with /api/v1/system/processes/unfreeze (SIGCONT) to resume.

Request Body

Field	Type	Required	Description
`pid`	integer	No	Process ID to freeze. Mutually exclusive with `name`. PIDs 1, 2, the server’s own PID, and the server’s parent PID are guarded and rejected with 403
`name`	string	No	Process name (case-insensitive `comm` match — freezes every matching process). Mutually exclusive with `pid`. Truncated to 15 characters by the kernel
`include_descendants`	boolean	No	When `true`, also freezes every descendant via a one-shot `/proc` PPID snapshot (bounded at 65535 PIDs). Default: `false`. The parent is signalled before descendants to shrink the fork/escape race window. With descendants, by-name dedupes overlapping subtrees so the same PID isn’t signalled twice

curl -X POST https://api.hoody.com/api/v1/system/processes/freeze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 4127,
    "include_descendants": true
  }'

await client.terminal.system.freezeProcess({
  data: {
    pid: 4127,
    include_descendants: true
  }
});

{
  "frozen": 12,
  "root_pid": 4127,
  "include_descendants": true
}

{
  "statusCode": 400,
  "error": "MISSING_TARGET",
  "message": "Must specify pid or name"
}

Error Code	Title	Description	Resolution
`MISSING_TARGET`	Must specify pid or name	Provide either pid or name parameter	Provide either pid or name parameter
`INVALID_PID`	pid must be a positive integer within int range	pid must be a positive integer within int range	Contact support

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "message": "PID 1 is guarded or kernel returned EPERM"
}

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	No permission to freeze process	Either the kernel returned EPERM (different UID) or the PID is in the guarded set (init/kthreadd/self/parent)	Either the kernel returned EPERM (different UID) or the PID is in the guarded set (init/kthreadd/self/parent)

{
  "statusCode": 404,
  "error": "PROCESS_NOT_FOUND",
  "message": "No process matching pid/name"
}

Error Code	Title	Description	Resolution
`PROCESS_NOT_FOUND`	No process matching pid/name	No process matching pid/name	Contact support

{
  "statusCode": 405,
  "error": "method_not_allowed",
  "message": "POST required"
}

{
  "statusCode": 500,
  "error": "FREEZE_FAILED",
  "message": "Failed to freeze process"
}

Error Code	Title	Description	Resolution
`FREEZE_FAILED`	Failed to freeze process	Check process exists	Check process exists
`PROC_SNAPSHOT_OOM`	/proc snapshot exhausted memory; transient	/proc snapshot exhausted memory; transient	Contact support
`PROC_TABLE_TOO_LARGE`	/proc PID table exceeds HT_PID_TABLE_MAX (65535)	/proc PID table exceeds HT_PID_TABLE_MAX (65535)	Contact support

`POST /api/v1/system/processes/unfreeze`

Resume execution of one or more previously-stopped processes by delivering SIGCONT. The body schema mirrors /freeze exactly. Calling unfreeze on a process that is already running is harmless — SIGCONT is a no-op for non-stopped processes.

Request Body

Field	Type	Required	Description
`pid`	integer	No	Process ID to unfreeze. Mutually exclusive with `name`. The guarded-PID set (1, 2, self, parent) is the same as for freeze
`name`	string	No	Process name (case-insensitive `comm` match). Mutually exclusive with `pid`. Truncated to 15 characters by the kernel
`include_descendants`	boolean	No	Also unfreeze all descendants via `/proc` PPID snapshot (bounded at 65535 PIDs). Default: `false`. By-name dedupes overlapping subtrees

curl -X POST https://api.hoody.com/api/v1/system/processes/unfreeze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pid": 4127,
    "include_descendants": true
  }'

await client.terminal.system.unfreezeProcess({
  data: {
    pid: 4127,
    include_descendants: true
  }
});

{
  "resumed": 12,
  "root_pid": 4127,
  "include_descendants": true
}

{
  "statusCode": 400,
  "error": "MISSING_TARGET",
  "message": "Must specify pid or name"
}

Error Code	Title	Description	Resolution
`MISSING_TARGET`	Must specify pid or name	Provide either pid or name parameter	Provide either pid or name parameter
`INVALID_PID`	pid must be a positive integer within int range	pid must be a positive integer within int range	Contact support

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "message": "PID 1 is guarded or kernel returned EPERM"
}

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	No permission to unfreeze process	Either the kernel returned EPERM (different UID) or the PID is in the guarded set (init/kthreadd/self/parent)	Either the kernel returned EPERM (different UID) or the PID is in the guarded set (init/kthreadd/self/parent)

{
  "statusCode": 404,
  "error": "PROCESS_NOT_FOUND",
  "message": "No process matching pid/name"
}

Error Code	Title	Description	Resolution
`PROCESS_NOT_FOUND`	No process matching pid/name	No process matching pid/name	Contact support

{
  "statusCode": 405,
  "error": "method_not_allowed",
  "message": "POST required"
}

{
  "statusCode": 500,
  "error": "UNFREEZE_FAILED",
  "message": "Failed to unfreeze process"
}

Error Code	Title	Description	Resolution
`UNFREEZE_FAILED`	Failed to unfreeze process	Check process exists	Check process exists
`PROC_SNAPSHOT_OOM`	/proc snapshot exhausted memory; transient	/proc snapshot exhausted memory; transient	Contact support
`PROC_TABLE_TOO_LARGE`	/proc PID table exceeds HT_PID_TABLE_MAX (65535)	/proc PID table exceeds HT_PID_TABLE_MAX (65535)	Contact support

System Power

`POST /api/v1/system/reboot`

Initiate a system reboot with optional delay. Requires root/sudo permissions — the Linux kernel enforces the check.

shutdown(8) schedules in whole minutes, so the server rounds up to the nearest minute and reports the actual scheduled value as effective_minutes in the response.

Parameters

Name	In	Type	Required	Description
`delay`	query	integer	No	Delay in seconds before reboot, `0..86400` (default: `0` for immediate). The server rounds up to the nearest whole minute

curl -X POST "https://api.hoody.com/api/v1/system/reboot?delay=60" \
  -H "Authorization: Bearer <token>"

await client.terminal.system.reboot({ delay: 60 });

{
  "scheduled": true,
  "effective_minutes": 1,
  "action": "reboot"
}

{
  "statusCode": 400,
  "error": "BAD_REQUEST",
  "message": "Delay out of range (> 86400)"
}

{
  "statusCode": 403,
  "error": "ROOT_REQUIRED",
  "message": "Reboot requires root privileges"
}

Error Code	Title	Description	Resolution
`ROOT_REQUIRED`	Reboot requires root privileges	Run with sudo or as root user	Run with sudo or as root user

{
  "statusCode": 405,
  "error": "method_not_allowed",
  "message": "POST required"
}

{
  "statusCode": 500,
  "error": "REBOOT_FAILED",
  "message": "Failed to execute reboot"
}

Error Code	Title	Description	Resolution
`REBOOT_FAILED`	Failed to execute reboot	Check system logs	Check system logs

`POST /api/v1/system/shutdown`

Initiate a system shutdown with optional delay. Requires root/sudo permissions — the Linux kernel enforces the check.

shutdown(8) schedules in whole minutes, so the server rounds up to the nearest minute and reports the actual scheduled value as effective_minutes in the response.

Parameters

Name	In	Type	Required	Description
`delay`	query	integer	No	Delay in seconds before shutdown, `0..86400` (default: `0` for immediate). The server rounds up to the nearest whole minute

curl -X POST "https://api.hoody.com/api/v1/system/shutdown?delay=120" \
  -H "Authorization: Bearer <token>"

await client.terminal.system.shutdown({ delay: 120 });

{
  "scheduled": true,
  "effective_minutes": 2,
  "action": "shutdown"
}

{
  "statusCode": 400,
  "error": "BAD_REQUEST",
  "message": "Delay out of range (> 86400)"
}

{
  "statusCode": 403,
  "error": "ROOT_REQUIRED",
  "message": "Shutdown requires root privileges"
}

Error Code	Title	Description	Resolution
`ROOT_REQUIRED`	Shutdown requires root privileges	Run with sudo or as root user	Run with sudo or as root user

{
  "statusCode": 405,
  "error": "method_not_allowed",
  "message": "POST required"
}

{
  "statusCode": 500,
  "error": "SHUTDOWN_FAILED",
  "message": "Failed to execute shutdown"
}

Error Code	Title	Description	Resolution
`SHUTDOWN_FAILED`	Failed to execute shutdown	Check system logs	Check system logs