Skip to content
Hoody.com

The Daemon Management API lets you manage custom programs running under the container’s supervisord instance. Two program types are supported:

  • Persistent programs — stored in programs.json and registered with supervisord. They survive container reboots and are intended for long-running services.
  • Ephemeral programs (Quick Start) — tracked in ephemeral.json only. They auto-clean when stopped, on container reboot, or when a TTL expires. Use them for one-off jobs, temporary test servers, and CI tasks.

All endpoints are scoped to the daemon container.

Persistent programs are stored in programs.json and registered with supervisord. Use programs/add for new custom programs, programs/edit/{id} to update an existing one, programs/remove/{id} to delete, and programs/reset to restore the default snapshot.

GET /api/v1/daemon/programs

Retrieves a complete list of all configured daemon programs with their full configuration details. Supports multiple filters that can be combined: hoody_kit, lazy_load, enabled, boot. Optionally include runtime status for each program.

NameInTypeRequiredDescription
hoody_kitquerystringNoFilter by hoody_kit status. Use "true" for Hoody Kit programs only, "false" for user (non-kit) programs only.
lazy_loadquerystringNoFilter by lazy_load status. Use "true" for lazy-loaded programs only (started on-demand), "false" for programs that auto-start.
enabledquerystringNoFilter by enabled status. Use "true" for enabled programs only, "false" for disabled programs only.
bootquerystringNoFilter by boot status. Use "true" for programs that auto-start on system boot, "false" for manual-start programs.
portqueryintegerNoFilter programs by single port number. Returns only programs whose port_range includes this specific port. Example: ?port=8042 returns programs with ranges containing 8042.
port_fromqueryintegerNoFilter by port range start (must be used with port_to). Returns programs whose port ranges overlap with the specified range. A program overlaps when its start is at most port_to and its end is at least port_from.
port_toqueryintegerNoFilter by port range end (must be used with port_from). Returns programs whose port ranges overlap with the specified range. Multiple programs may be returned if their ranges overlap.
include_statusquerystringNoInclude runtime status for each program. When true, adds a status field to each program showing current running state, instances, and process details.
include_statsquerystringNoInclude resource stats (CPU, memory, process tree) for each running program. Implies include_status=true. Adds a stats field with pid, started_at, cpu_percent, memory_rss_bytes, process_count, and per-process breakdown. Only present for running programs.
Terminal window
curl -X GET "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs?enabled=true&include_status=true" \
-H "Authorization: Bearer <your-token>"

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

Retrieves detailed configuration for a single program by its unique ID. Returns complete program configuration including all optional fields.

NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program
Terminal window
curl -X GET "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs/1" \
-H "Authorization: Bearer <your-token>"

POST /api/v1/daemon/programs/add

Creates a new daemon program from a JSON request body. The program is validated, added to the configuration, and registered with supervisord if enabled.

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.

This endpoint takes no parameters.

NameTypeRequiredDefaultDescription
idintegerNoSpecific ID to assign (auto-assigned if not provided)
namestringYesProgram name (must be unique, cannot contain quotes)
descriptionstringNoHuman-readable description (max 500 chars)
commandstringYesFull command to execute including all arguments. Use for custom programs only — node app.js, python main.py, ruby server.rb. Do not use for system services like apache2, nginx, postgresql; use systemctl for those.
userstringYesSystem user to run as (must exist on the system)
enabledbooleanNotrueEnable the program immediately
bootbooleanNofalseStart automatically on system boot
delay_secondsintegerNo0Seconds to wait before starting on boot (max 3600)
autorestartstringNo"unexpected"Restart policy: "true", "false", or "unexpected"
directorystringNoWorking directory path
priorityintegerNo999Start priority (1-999, lower starts first)
stdout_logfilestringNoPath for standard output log
stderr_logfilestringNoPath for standard error log
logs_enabledbooleanNotrueWhether logging is enabled
log_max_bytesintegerNo5242880Maximum size of each log file in bytes before rotation
log_backupsintegerNo2Number of rotated backup log files to keep (max 100)
environmentobjectNoEnvironment variables as key-value strings
hoody_kitbooleanNofalseRead-only. Server-derived from the program directory (true iff under /hoody/plugins). Any value supplied in a create/update request body is ignored.
port_rangeobjectNoPort range for multi-instance programs. Each port creates a separate instance. Contains start and end (1-65535).
port_paramstringNo"--port"Parameter name for passing port (e.g., "--port", "-p")
lazy_loadbooleanNofalseEnable lazy loading (autostart=false). Cannot be combined with boot:true.
displaystringNoX11 DISPLAY number for GUI programs (e.g., ":1")
terminal_idintegerNoHoody Terminal session ID (1-65535). Enables web-based terminal access via hoody-terminal.
terminal_shellstringNoHoody Terminal shell wrapper. One of bash, zsh, fish, sh, tmux. Requires terminal_id.
terminal_interactivebooleanNoOverride auto-detection of interactive vs service mode for hoody-terminal.
webhooksobjectNoWebhook notification configuration for program lifecycle events
Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs/add" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "nodejs-app",
"description": "Production Node.js application",
"command": "node server.js",
"user": "nodejs",
"enabled": true,
"boot": true,
"delay_seconds": 10,
"autorestart": "unexpected",
"directory": "/opt/myapp",
"priority": 100,
"environment": {
"NODE_ENV": "production",
"PORT": "3000",
"DATABASE_URL": "postgresql://localhost/mydb"
},
"stdout_logfile": "/var/log/myapp/stdout.log",
"stderr_logfile": "/var/log/myapp/stderr.log"
}'

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

Updates an existing program configuration using JSON request body. Only provided fields will be updated — unspecified fields retain their current values.

NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program
NameTypeRequiredDefaultDescription
idintegerNoSpecific ID to assign (auto-assigned if not provided)
namestringYesProgram name (must be unique, cannot contain quotes)
descriptionstringNoHuman-readable description (max 500 chars)
commandstringYesFull command to execute including all arguments. Use for custom programs only — node app.js, python main.py, ruby server.rb. Do not use for system services like apache2, nginx, postgresql; use systemctl for those.
userstringYesSystem user to run as (must exist on the system)
enabledbooleanNotrueEnable the program immediately
bootbooleanNofalseStart automatically on system boot
delay_secondsintegerNo0Seconds to wait before starting on boot (max 3600)
autorestartstringNo"unexpected"Restart policy: "true", "false", or "unexpected"
directorystringNoWorking directory path
priorityintegerNo999Start priority (1-999, lower starts first)
stdout_logfilestringNoPath for standard output log
stderr_logfilestringNoPath for standard error log
logs_enabledbooleanNotrueWhether logging is enabled
log_max_bytesintegerNo5242880Maximum size of each log file in bytes before rotation
log_backupsintegerNo2Number of rotated backup log files to keep (max 100)
environmentobjectNoEnvironment variables as key-value strings
hoody_kitbooleanNofalseRead-only. Server-derived from the program directory (true iff under /hoody/plugins). Any value supplied in a create/update request body is ignored.
port_rangeobjectNoPort range for multi-instance programs. Each port creates a separate instance. Contains start and end (1-65535).
port_paramstringNo"--port"Parameter name for passing port (e.g., "--port", "-p")
lazy_loadbooleanNofalseEnable lazy loading (autostart=false). Cannot be combined with boot:true.
displaystringNoX11 DISPLAY number for GUI programs (e.g., ":1")
terminal_idintegerNoHoody Terminal session ID (1-65535). Enables web-based terminal access via hoody-terminal.
terminal_shellstringNoHoody Terminal shell wrapper. One of bash, zsh, fish, sh, tmux. Requires terminal_id.
terminal_interactivebooleanNoOverride auto-detection of interactive vs service mode for hoody-terminal.
webhooksobjectNoWebhook notification configuration for program lifecycle events
Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs/edit/1" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "nodejs-app",
"description": "Completely updated application",
"command": "node app.js",
"user": "nodejs",
"enabled": true,
"boot": true,
"delay_seconds": 15,
"autorestart": "unexpected",
"directory": "/opt/newpath",
"priority": 50,
"environment": {
"NODE_ENV": "production"
}
}'

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

Permanently deletes a program from the configuration. If the program is running, it will be stopped before removal. This is a destructive operation that cannot be undone.

NameInTypeRequiredDescription
idpathintegerYesUnique numeric identifier of the program
Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs/remove/1" \
-H "Authorization: Bearer <your-token>"

POST /api/v1/daemon/programs/reset

Replaces the current programs.json with the initial default snapshot (programs.default.json) created at container setup time. Stops all managed programs, removes their supervisord configs, and re-applies the default boot programs. Use this when programs have been misconfigured and a clean slate is needed.

This endpoint takes no parameters.

Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/programs/reset" \
-H "Authorization: Bearer <your-token>"

Ephemeral programs are temporary programs created via Quick Start. They are NOT saved to programs.json — they are tracked in ephemeral.json for crash recovery only. They auto-clean on manual stop, program exit, container reboot, or TTL expiry.

Use Quick Start for one-off migrations, temporary test servers, debug tasks, CI ephemeral environments, and custom batch jobs. For permanent programs that must survive reboots, use POST /programs/add instead.

GET /api/v1/daemon/quick-start

Returns all currently tracked ephemeral programs with their current runtime status. Shows programs that are running or pending cleanup.

This endpoint takes no parameters.

Terminal window
curl -X GET "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/quick-start" \
-H "Authorization: Bearer <your-token>"

POST /api/v1/daemon/quick-start

Creates and starts a temporary custom program that auto-cleans when stopped or on container reboot. Custom programs only — system services (apache2, nginx, etc.) belong under systemctl.

Key features:

  • Not saved to programs.json (temporary only)
  • Tracked in ephemeral.json for crash recovery
  • Always created with autostart=false (does not auto-start on reboot)
  • Auto-cleanup on: manual stop, program exit, container reboot, TTL expiry
  • Full supervisord configuration support (autorestart, environment, logs, etc.)

Suited to: one-off data migrations, temporary test servers, debug/dev tasks, CI/CD ephemeral environments, custom batch jobs.

  • Use for: python my_migration.py, node test-server.js, ./my-batch-job.sh
  • Don’t use for: system services like apache2, nginx, postgresql — use systemctl.

Use POST /programs/add for permanent custom programs that must survive reboots.

This endpoint takes no parameters.

NameTypeRequiredDefaultDescription
commandstringYesCommand to execute with full arguments
userstringYesSystem user to run as (must exist on the system)
namestringNoCustom name (auto-generated if not provided). Cannot contain quotes
autorestartstringNo"unexpected"Restart policy while running: "true", "false", or "unexpected"
directorystringNoWorking directory (defaults to user home if not specified)
environmentobjectNoEnvironment variables as key-value strings
priorityintegerNo999Start priority (1-999, lower starts first)
delay_secondsintegerNo0Delay before starting (seconds, max 3600)
stdout_logfilestringNoPath for standard output log
stderr_logfilestringNoPath for standard error log
logs_enabledbooleanNotrueWhether logging is enabled
log_max_bytesintegerNo5242880Maximum size of each log file in bytes before rotation
log_backupsintegerNo2Number of rotated backup log files to keep (max 100)
ttlintegerNoTime-to-live in seconds. Program auto-stops after this duration (1-86400)
waitbooleanNofalseWait for program to reach RUNNING state before returning
timeoutintegerNo30Timeout in seconds when wait=true (1-300)
displaystringNoX11 DISPLAY number for GUI programs
terminal_idintegerNoHoody Terminal session ID (1-65535)
terminal_shellstringNoHoody Terminal shell wrapper
terminal_interactivebooleanNoOverride auto-detection of interactive vs service mode
Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/quick-start" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"command": "python batch-job.py",
"user": "worker",
"name": "data-migration",
"autorestart": "unexpected",
"directory": "/opt/scripts",
"environment": {
"DB_HOST": "localhost",
"MODE": "production"
},
"ttl": 3600,
"wait": true
}'

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

Retrieves current runtime status for a specific ephemeral program by its temporary_id.

NameInTypeRequiredDescription
idpathstringYesTemporary ID of the ephemeral program (format: quick_<timestamp>)
Terminal window
curl -X GET "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/quick-start/quick_1731605123/status" \
-H "Authorization: Bearer <your-token>"

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

Retrieve the last N lines from an ephemeral program’s stdout or stderr log file.

NameInTypeRequiredDescription
idpathstringYesEphemeral program temporary ID
typequerystringNoLog stream: stdout or stderr. Default: "stdout"
linesqueryintegerNoNumber of lines to return from end of file. Default: 100
Terminal window
curl -X GET "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/quick-start/quick_1731605123/logs?type=stdout&lines=50" \
-H "Authorization: Bearer <your-token>"

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

Stops the ephemeral program and removes its configuration completely.

Actions performed:

  1. Stop program via supervisorctl
  2. Delete supervisord config file
  3. Remove from ephemeral.json tracking
  4. Update supervisord

Result: Program is completely removed from the system (cannot be restarted).

NameInTypeRequiredDescription
idpathstringYesTemporary ID of the ephemeral program to stop
Terminal window
curl -X POST "https://myproj-abc12345-daemon-1.us-east-1.containers.hoody.icu/api/v1/daemon/quick-start/quick_1731605123/stop" \
-H "Authorization: Bearer <your-token>"