# Daemon Management

**Page:** api/daemon/management

[Download Raw Markdown](./api/daemon/management.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Daemon Management API lets you list, inspect, create, update, and remove supervised programs running in your container. It also covers ephemeral ("Quick Start") programs — short-lived processes that auto-clean when stopped or on container reboot. Use these endpoints to register custom applications (Node.js, Python, Ruby, custom binaries) and manage their lifecycle. System services (`apache2`, `nginx`, `postgresql`, `mysql`, etc.) are managed separately via `systemctl`.


Custom programs only. Endpoints in this section target supervised user programs. For system services, use the `systemctl` API instead.


---

## Programs

### `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 and resource stats for each program.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `hoody_kit` | query | string | No | Filter by hoody_kit status. Use `"true"` for Hoody Kit programs only, `"false"` for official programs only. |
| `lazy_load` | query | string | No | Filter by lazy_load status. Use `"true"` for lazy-loaded programs only (started on-demand), `"false"` for programs that auto-start. |
| `enabled` | query | string | No | Filter by enabled status. Use `"true"` for enabled programs only, `"false"` for disabled programs only. |
| `boot` | query | string | No | Filter by boot status. Use `"true"` for programs that auto-start on system boot, `"false"` for manual-start programs. |
| `port` | query | integer | No | Filter programs by single port number. Returns only programs whose `port_range` includes this specific port. |
| `port_from` | query | integer | No | Filter by port range start (must be used with `port_to`). Returns programs whose port ranges overlap with the specified range. |
| `port_to` | query | integer | No | Filter by port range end (must be used with `port_from`). Returns programs whose port ranges overlap with the specified range. |
| `include_status` | query | string | No | Include runtime status for each program. When `true`, adds a `status` field to each program showing current running state, instances, and process details. |
| `include_stats` | query | string | No | Include 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. |




```bash
curl "https://your-host/api/v1/daemon/programs?enabled=true&include_status=true"
```




```js
// List all enabled programs with runtime status
const programs = await client.daemon.programs.listIterator({
  enabled: "true",
  include_status: "true"
});
```




#### Response




**Multiple programs configured**

```json
{
  "programs": [
    {
      "id": 1,
      "name": "web-server",
      "description": "Nginx web server",
      "enabled": true,
      "command": "nginx -g \"daemon off;\"",
      "boot": true,
      "delay_seconds": 5,
      "autorestart": "unexpected",
      "user": "www-data",
      "environment": {
        "NGINX_PORT": "80"
      },
      "directory": "/var/www",
      "priority": 999,
      "stdout_logfile": "/var/log/nginx/access.log",
      "stderr_logfile": "/var/log/nginx/error.log",
      "hoody_kit": false
    },
    {
      "id": 2,
      "name": "nodejs-app",
      "description": "Production Node.js application",
      "enabled": true,
      "command": "node server.js",
      "boot": true,
      "delay_seconds": 10,
      "autorestart": "unexpected",
      "user": "nodejs",
      "environment": {
        "NODE_ENV": "production",
        "PORT": "3000"
      },
      "directory": "/opt/myapp",
      "priority": 100,
      "stdout_logfile": "/var/log/myapp/stdout.log",
      "stderr_logfile": "/var/log/myapp/stderr.log",
      "hoody_kit": false
    }
  ]
}
```

**No programs configured**

```json
{
  "programs": []
}
```




---

### `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.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | integer | Yes | Unique numeric identifier of the program. |




```bash
curl "https://your-host/api/v1/daemon/programs/1"
```




```js
const program = await client.daemon.programs.get({ id: 1 });
```




#### Response




```json
{
  "success": true,
  "program": {
    "id": 1,
    "name": "web-server",
    "description": "Nginx web server",
    "enabled": true,
    "command": "nginx -g \"daemon off;\"",
    "boot": true,
    "delay_seconds": 5,
    "autorestart": "unexpected",
    "user": "www-data",
    "environment": {},
    "directory": "/var/www",
    "priority": 999
  }
}
```




```json
{
  "success": false,
  "error": "Program with ID 999 not found"
}
```




---

### `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.


Custom programs only — your own code/scripts (e.g. `node app.js`, `python my_script.py`, `./my-binary`). Do not use this endpoint for system services such as `apache2`, `nginx`, `postgresql`, or `mysql`; manage those with `systemctl`.


### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Program name — must be unique, cannot contain quotes. |
| `command` | string | Yes | Full command to execute including all arguments. Use for custom programs only. |
| `user` | string | Yes | System user account to run the program as (must exist on the system). |
| `id` | integer | No | Specific ID to assign (auto-assigned if not provided). |
| `description` | string | No | Human-readable description (max 500 chars). |
| `enabled` | boolean | No | Enable the program immediately. Default: `true`. |
| `boot` | boolean | No | Start automatically on system boot. Default: `false`. |
| `delay_seconds` | integer | No | Startup delay in seconds (0–3600). Default: `0`. |
| `autorestart` | string | No | Restart policy. One of `"true"`, `"false"`, `"unexpected"`. Default: `"unexpected"`. |
| `directory` | string | No | Working directory path. |
| `priority` | integer | No | Start priority (1–999, lower starts first). Default: `999`. |
| `stdout_logfile` | string | No | Path for standard output log. |
| `stderr_logfile` | string | No | Path for standard error log. |
| `logs_enabled` | boolean | No | Whether logging is enabled. Default: `true`. |
| `log_max_bytes` | integer | No | Maximum size of each log file in bytes before rotation. Default: `5242880` (5MB). |
| `log_backups` | integer | No | Number of rotated backup log files to keep. Default: `2`. |
| `environment` | object | No | Environment variables as key-value string pairs. |
| `hoody_kit` | boolean | No | Whether this is a Hoody Kit program (auto-detected from directory path). Default: `false`. |
| `port_range` | object | No | Port range for multi-instance programs. Requires `start` and `end`. |
| `port_param` | string | No | Parameter name for passing port (e.g. `"--port"`). Default: `"--port"`. |
| `lazy_load` | boolean | No | Enable lazy loading (autostart=false). Cannot be combined with `boot:true`. Default: `false`. |
| `display` | string | No | X11 DISPLAY number for GUI programs (e.g. `":1"`). |
| `terminal_id` | integer | No | Hoody Terminal session ID (1–65535) for web-based terminal access. |
| `terminal_shell` | string | No | Shell for environment loading. One of `"bash"`, `"zsh"`, `"fish"`, `"sh"`, `"tmux"`. |
| `terminal_interactive` | boolean | No | Override interactive vs service mode. |
| `webhooks` | object | No | Webhook notification configuration for lifecycle events. |




```bash
curl -X POST "https://your-host/api/v1/daemon/programs/add" \
  -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"
  }'
```




```js
const result = await client.daemon.programs.add({
  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"
});
```




#### Response




```json
{
  "success": true,
  "id": 2,
  "program": {
    "id": 2,
    "name": "nodejs-app",
    "description": "Node.js application",
    "enabled": true,
    "command": "node app.js",
    "boot": false,
    "delay_seconds": 0,
    "autorestart": "unexpected",
    "user": "nodejs",
    "environment": {
      "NODE_ENV": "production"
    },
    "directory": "/opt/app",
    "priority": 999
  }
}
```




**Validation error**

```json
{
  "success": false,
  "error": "Field 'command' is required and must be a non-empty string"
}
```

**System user does not exist**

```json
{
  "success": false,
  "error": "User \"invalid-user\" does not exist on the system"
}
```




---

### `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.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | integer | Yes | Unique numeric identifier of the program. |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Program name — must be unique, cannot contain quotes. |
| `command` | string | No | Full command to execute including all arguments. |
| `user` | string | No | System user account to run the program as. |
| `description` | string | No | Human-readable description (max 500 chars). |
| `enabled` | boolean | No | Whether the program is currently enabled. |
| `boot` | boolean | No | Start automatically on system boot. |
| `delay_seconds` | integer | No | Startup delay in seconds (0–3600). |
| `autorestart` | string | No | Restart policy. One of `"true"`, `"false"`, `"unexpected"`. |
| `directory` | string | No | Working directory path. |
| `priority` | integer | No | Start priority (1–999). |
| `environment` | object | No | Environment variables as key-value string pairs. |
| `webhooks` | object | No | Webhook notification configuration. |
| `lazy_load` | boolean | No | Enable lazy loading. Cannot be combined with `boot:true`. |
| `display` | string | No | X11 DISPLAY number for GUI programs. |
| `terminal_id` | integer | No | Hoody Terminal session ID (1–65535). |
| `terminal_shell` | string | No | Shell for environment loading. |
| `stdout_logfile` | string | No | Path for standard output log. |
| `stderr_logfile` | string | No | Path for standard error log. |




```bash
curl -X POST "https://your-host/api/v1/daemon/programs/edit/1" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "command": "node server.js --production",
    "environment": {
      "NODE_ENV": "production",
      "PORT": "8080"
    }
  }'
```




```js
const result = await client.daemon.programs.edit({
  id: 1,
  description: "Updated description",
  command: "node server.js --production",
  environment: {
    NODE_ENV: "production",
    PORT: "8080"
  }
});
```




#### Response




```json
{
  "success": true,
  "program": {
    "id": 1,
    "name": "nodejs-app",
    "description": "Updated description",
    "enabled": true,
    "command": "node server.js --production",
    "boot": true,
    "delay_seconds": 5,
    "autorestart": "unexpected",
    "user": "nodejs",
    "environment": {
      "NODE_ENV": "production",
      "PORT": "8080"
    },
    "directory": "/opt/app",
    "priority": 999
  }
}
```




```json
{
  "success": false,
  "error": "Field 'autorestart' must be one of: true, false, unexpected"
}
```




```json
{
  "success": false,
  "error": "Program with ID 1 not found"
}
```




---

### `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.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | integer | Yes | Unique numeric identifier of the program. |




```bash
curl -X POST "https://your-host/api/v1/daemon/programs/remove/1"
```




```js
await client.daemon.programs.remove({ id: 1 });
```




#### Response




```json
{
  "success": true,
  "id": 1
}
```




```json
{
  "success": false,
  "error": "Program with ID 1 not found"
}
```




---

### `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.




```bash
curl -X POST "https://your-host/api/v1/daemon/programs/reset"
```




```js
await client.daemon.programs.reset();
```




#### Response




```json
{
  "success": true
}
```




```json
{
  "success": false,
  "error": "Default programs file (programs.default.json) is missing or corrupt"
}
```




---

## Quick Start (Ephemeral Programs)

Quick Start lets you run temporary custom programs that auto-clean when stopped or on container reboot. Programs are not saved to `programs.json`; they are tracked in `ephemeral.json` for crash recovery. Use them for one-off data migrations, temporary test servers, debug tasks, CI/CD ephemeral environments, and custom batch jobs. For permanent programs that must survive reboots, use `POST /api/v1/daemon/programs/add`.

### `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.




```bash
curl "https://your-host/api/v1/daemon/quick-start"
```




```js
const ephemeral = await client.daemon.quickStart.listIterator();
```




#### Response




**Multiple ephemeral programs**

```json
{
  "success": true,
  "count": 2,
  "ephemeral_programs": [
    {
      "temporary_id": "quick_1731605123",
      "name": "quick_python_1731605123",
      "command": "python batch-job.py",
      "user": "worker",
      "status": "running",
      "created_at": "2024-11-14T18:32:03Z",
      "uptime": "0:05:32"
    },
    {
      "temporary_id": "quick_1731605456",
      "name": "my-temp-server",
      "command": "node server.js",
      "user": "nodejs",
      "status": "running",
      "created_at": "2024-11-14T18:37:36Z",
      "expires_at": "2024-11-14T19:37:36Z",
      "uptime": "0:00:08"
    }
  ]
}
```

**No ephemeral programs**

```json
{
  "success": true,
  "count": 0,
  "ephemeral_programs": []
}
```




---

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

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

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Temporary ID of the ephemeral program (format: `quick_<timestamp>`). |




```bash
curl "https://your-host/api/v1/daemon/quick-start/quick_1731605123/status"
```




```js
const status = await client.daemon.quickStart.getStatus({ id: "quick_1731605123" });
```




#### Response




**Program is running**

```json
{
  "success": true,
  "temporary_id": "quick_1731605123",
  "name": "quick_python_1731605123",
  "status": "running",
  "pid": 12345,
  "uptime": "0:15:30",
  "created_at": "2024-11-14T18:32:03Z"
}
```

**Program is stopped**

```json
{
  "success": true,
  "temporary_id": "quick_1731605123",
  "name": "quick_python_1731605123",
  "status": "stopped",
  "created_at": "2024-11-14T18:32:03Z"
}
```

**Program with TTL expiry**

```json
{
  "success": true,
  "temporary_id": "quick_1731605456",
  "name": "my-temp-server",
  "status": "running",
  "pid": 12350,
  "uptime": "0:02:10",
  "created_at": "2024-11-14T18:37:36Z",
  "expires_at": "2024-11-14T19:37:36Z"
}
```




```json
{
  "success": false,
  "error": "Ephemeral program with ID quick_1731605123 not found"
}
```




---

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

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

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Ephemeral program temporary ID. |
| `type` | query | string | No | Log stream. One of `"stdout"`, `"stderr"`. Default: `"stdout"`. |
| `lines` | query | integer | No | Number of lines to return from end of file. Default: `100`. |




```bash
curl "https://your-host/api/v1/daemon/quick-start/quick_1731605123/logs?type=stdout&lines=50"
```




```js
const logs = await client.daemon.quickStart.getEphemeralLogs({
  id: "quick_1731605123",
  type: "stdout",
  lines: 50
});
```




#### Response




```json
{
  "success": true,
  "logs": "2024-11-14 18:32:03 INFO Starting batch job\n2024-11-14 18:32:05 INFO Processing 100 records\n2024-11-14 18:32:10 INFO Job completed",
  "type": "stdout",
  "lines": 100,
  "log_file": "/var/log/myapp/stdout.log"
}
```




```json
{
  "success": false,
  "error": "Invalid 'type' value: must be 'stdout' or 'stderr'"
}
```




```json
{
  "success": false,
  "error": "Ephemeral program with ID quick_1731605123 not found"
}
```




---

### `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 behaviors:

- 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.)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command` | string | Yes | Command to execute with full arguments for your custom program/script. |
| `user` | string | Yes | System user to run as (must exist on the system). |
| `name` | string | No | Custom name (auto-generated if not provided). Cannot contain quotes. |
| `autorestart` | string | No | Restart policy. One of `"true"`, `"false"`, `"unexpected"`. Default: `"unexpected"`. |
| `directory` | string | No | Working directory (defaults to user home if not specified). |
| `environment` | object | No | Environment variables as key-value string pairs. |
| `priority` | integer | No | Start priority (1–999, lower starts first). Default: `999`. |
| `delay_seconds` | integer | No | Delay before starting (seconds, 0–3600). Default: `0`. |
| `stdout_logfile` | string | No | Path for standard output log. |
| `stderr_logfile` | string | No | Path for standard error log. |
| `logs_enabled` | boolean | No | Whether logging is enabled. Default: `true`. |
| `log_max_bytes` | integer | No | Maximum log file size in bytes before rotation. Default: `5242880` (5MB). |
| `log_backups` | integer | No | Number of rotated backup log files to keep. Default: `2`. |
| `ttl` | integer | No | Time-to-live in seconds. Program auto-stops after this duration (1–86400). |
| `wait` | boolean | No | Wait for program to reach `RUNNING` state before returning. Default: `false`. |
| `timeout` | integer | No | Timeout in seconds when `wait=true` (1–300). Default: `30`. |
| `display` | string | No | X11 DISPLAY number for GUI programs. |
| `terminal_id` | integer | No | Hoody Terminal session ID (1–65535). |
| `terminal_shell` | string | No | Shell for environment loading. One of `"bash"`, `"zsh"`, `"fish"`, `"sh"`, `"tmux"`. |
| `terminal_interactive` | boolean | No | Override interactive vs service mode. |




```bash
curl -X POST "https://your-host/api/v1/daemon/quick-start" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "node test-server.js",
    "user": "nodejs",
    "name": "temp-test-server",
    "directory": "/opt/test",
    "ttl": 1800,
    "environment": {
      "PORT": "9999",
      "NODE_ENV": "test"
    },
    "wait": true
  }'
```




```js
const result = await client.daemon.quickStart.launch({
  command: "node test-server.js",
  user: "nodejs",
  name: "temp-test-server",
  directory: "/opt/test",
  ttl: 1800,
  environment: {
    PORT: "9999",
    NODE_ENV: "test"
  },
  wait: true
});
```




#### Response




**Program started (without wait)**

```json
{
  "success": true,
  "temporary_id": "quick_1731605123",
  "name": "quick_node_1731605123",
  "status": "starting",
  "created_at": "2024-11-14T18:32:03Z"
}
```

**Program started (with wait=true)**

```json
{
  "success": true,
  "temporary_id": "quick_1731605123",
  "name": "temp-test-server",
  "status": "running",
  "pid": 12345,
  "uptime": "0:00:05",
  "created_at": "2024-11-14T18:32:03Z"
}
```

**Program with TTL (auto-stop)**

```json
{
  "success": true,
  "temporary_id": "quick_1731605456",
  "name": "temp-test-server",
  "status": "running",
  "pid": 12350,
  "uptime": "0:00:08",
  "created_at": "2024-11-14T18:37:36Z",
  "expires_at": "2024-11-14T19:37:36Z"
}
```




**Required field missing**

```json
{
  "success": false,
  "error": "Field 'command' is required and must be a non-empty string"
}
```

**System user does not exist**

```json
{
  "success": false,
  "error": "User \"invalid-user\" does not exist on the system"
}
```

**Directory does not exist**

```json
{
  "success": false,
  "error": "Working directory '/opt/missing' does not exist"
}
```

**Name contains quotes**

```json
{
  "success": false,
  "error": "Name must not contain quote characters"
}
```




---

### `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).

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | Temporary ID of the ephemeral program to stop. |




```bash
curl -X POST "https://your-host/api/v1/daemon/quick-start/quick_1731605123/stop"
```




```js
await client.daemon.quickStart.stop({ id: "quick_1731605123" });
```




#### Response




```json
{
  "success": true,
  "temporary_id": "quick_1731605123",
  "cleaned_up": true,
  "message": "Program stopped and configuration removed"
}
```




```json
{
  "success": false,
  "error": "Ephemeral program with ID quick_1731605123 not found"
}
```