<!--
hoody-daemon Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-19T22:52:18.152Z
Model: mimo-v2.5-pro + fixer:z-ai/glm-5.1
Mode: cli


Tokens: 7333

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-daemon Subskill

## Overview

### Purpose

hoody-daemon manages long-running processes inside Hoody containers via supervisord. It provides lifecycle control for persistent services, worker processes, and ephemeral tasks—all accessible through the `hoody daemon` CLI group.

### When to Use

- **Custom application servers** you deploy (Node.js, Python, Go backends)
- **Background workers** (queue processors, cron-like services)
- **Port-range programs** for multi-instance scaling
- **Ephemeral tasks** that should auto-clean after stopping
- **System service monitoring** (viewing status of apache2, nginx, etc.)

### Philosophy Alignment

hoody-daemon embodies Hoody's service management philosophy: declarative configuration, supervised processes, and HTTP-accessible control. Programs are defined in configuration, managed by supervisord, and controlled via CLI commands that map to daemon API endpoints. Never call the HTTP endpoints directly—always use `hoody daemon` commands.

### Key Concepts

| Concept | Description |
|---------|-------------|
| **Persistent Program** | Long-running service stored in `programs.json` |
| **Ephemeral Program** | Temporary task via quick-start, auto-cleans on stop/reboot |
| **Port-Range Program** | Multi-instance program spanning a port range (max 1000 ports) |
| **Enable/Disable** | Controls whether a program is registered with supervisord |
| **Start/Stop** | Controls whether a running program is active |

---

## Common Workflows

### Workflow 1: Health Check and Service Discovery

Verify the daemon is responsive, then explore available programs.

```
# Step 1: Check daemon health
hoody daemon health -c my-container

# Step 2: List all configured programs with their status
hoody daemon list -c my-container

# Step 3: Get detailed status of all programs
hoody daemon statuses -c my-container -o json
```

**Verification**: Health returns a JSON response with `"status": "ok"`. The list shows program names, IDs, and enabled/boot flags.

---

### Workflow 2: Deploy a Custom Program

Add a new long-running service to a container.

```
# Step 1: Create the program configuration
hoody daemon create -c my-container -o json \
  --name "my-api-server" \
  --command "node /app/server.js" \
  --user "www-data" \
  --port-range-start 3000 \
  --port-range-end 3010

# Step 2: Verify creation by listing
hoody daemon list -c my-container

# Step 3: Enable the program (registers with supervisord)
hoody daemon enable my-api-server -c my-container

# Step 4: Start the program
hoody daemon start my-api-server -c my-container

# Step 5: Confirm it's running
hoody daemon status my-api-server -c my-container -o json
```

**Verification**: Status shows `"state": "RUNNING"` with process details.

---

### Workflow 3: View and Manage Program Logs

Inspect logs for debugging a running program.

```
# Get recent logs for a program
hoody daemon logs my-api-server -c my-container

# Get logs with specific line count (if supported)
hoody daemon logs my-api-server -c my-container --lines 100
```

**Verification**: Log output appears in terminal. Look for startup messages or error traces.

---

### Workflow 4: Restart a Program

Stop and start a program to apply configuration changes.

```
# Step 1: Stop the program
hoody daemon stop my-api-server -c my-container

# Step 2: Verify stopped state
hoody daemon status my-api-server -c my-container -o json

# Step 3: Start the program again
hoody daemon start my-api-server -c my-container

# Step 4: Confirm running state
hoody daemon status my-api-server -c my-container -o json
```

**Verification**: Status transitions from `"RUNNING"` to `"STOPPED"` back to `"RUNNING"`.

---

### Workflow 5: Run an Ephemeral Task

Execute a temporary process that auto-cleans when stopped.

```
# Step 1: Launch ephemeral program
hoody daemon start -c my-container -o json \
  --command "python /scripts/migration.py" \
  --user "app"
# Note the returned id field for subsequent steps

# Step 2: List active ephemeral programs
hoody daemon list -c my-container

# Step 3: Check ephemeral program status
hoody daemon status <ephemeral-id> -c my-container -o json

# Step 4: View logs from ephemeral program
hoody daemon logs <ephemeral-id> -c my-container

# Step 5: Stop ephemeral program (removes config automatically)
hoody daemon stop <ephemeral-id> -c my-container
```

**Verification**: After stopping, the ephemeral program disappears from the list.

---

### Workflow 6: Edit an Existing Program

Update configuration of a managed program.

```
# Step 1: View current configuration
hoody daemon get my-api-server -c my-container -o json

# Step 2: Edit the program (only provided fields update)
hoody daemon edit my-api-server -c my-container -o json \
  --command "node /app/server-v2.js" \
  --user "www-data" \
  --port-range-start 3000 \
  --port-range-end 3010

# Step 3: Restart to apply changes
hoody daemon stop my-api-server -c my-container
hoody daemon start my-api-server -c my-container

# Step 4: Verify new configuration
hoody daemon get my-api-server -c my-container -o json
```

**Verification**: The `command` field reflects the updated path.

---

### Workflow 7: Remove a Program

Permanently delete a program from the container.

```
# Step 1: Stop the program first
hoody daemon stop my-api-server -c my-container

# Step 2: Remove the program (requires --yes confirmation)
hoody daemon delete my-api-server -c my-container --yes

# Step 3: Verify removal
hoody daemon list -c my-container
```

**Verification**: The program no longer appears in the list.

---

## Advanced Operations

### Advanced Workflow 1: Reset All Programs to Defaults

Restore the original program configuration created at container setup time.

```
# Step 1: Document current state before reset
hoody daemon list -c my-container -o json > programs-backup.json

# Step 2: Reset to default configuration
hoody daemon reset -c my-container

# Step 3: Verify default programs are restored
hoody daemon list -c my-container -o json
```

**What happens internally**:
1. All managed programs are stopped
2. Supervisord configs are removed
3. `programs.default.json` replaces `programs.json`
4. Programs are re-registered with supervisord

**⚠️ Warning**: This destroys all custom program configurations. Back up first.

---

### Advanced Workflow 2: Port-Range Program Scaling

Manage multi-instance programs that span a port range.

```
# Step 1: Create port-range program (max 1000 ports)
hoody daemon create -c my-container -o json \
  --name "worker-pool" \
  --command "node /app/worker.js --port ${PORT}" \
  --user "app" \
  --port-range-start 4000 \
  --port-range-end 4050

# Step 2: Enable and start
hoody daemon enable worker-pool -c my-container
hoody daemon start worker-pool -c my-container

# Step 3: Start a specific port instance
hoody daemon start worker-pool -c my-container --port 4001

# Step 4: Stop a specific port instance
hoody daemon stop worker-pool -c my-container --port 4001

# Step 5: Stop all port instances
hoody daemon stop worker-pool -c my-container --all
```

---

### Advanced Workflow 3: Program Lifecycle with Disabled State

Disable a program without deleting it, then re-enable later.

```
# Step 1: Disable program (stops it and removes from supervisord)
hoody daemon disable my-api-server -c my-container

# Step 2: Verify disabled state
hoody daemon get my-api-server -c my-container -o json
# Note: "enabled" field is false

# Step 3: Later, re-enable
hoody daemon enable my-api-server -c my-container

# Step 4: Start the re-enabled program
hoody daemon start my-api-server -c my-container
```

**Use case**: Temporarily disable a service during maintenance without losing configuration.

---

### Advanced Workflow 4: Error Recovery for Failed Programs

Diagnose and recover from program failures.

```
# Step 1: Check all program statuses
hoody daemon statuses -c my-container -o json

# Step 2: Identify failed programs (state != RUNNING)
# Step 3: View logs for the failed program
hoody daemon logs my-api-server -c my-container

# Step 4: Fix the issue (e.g., edit configuration)
hoody daemon edit my-api-server -c my-container -o json \
  --name "my-api-server" \
  --command "node /app/server.js --fix-flag" \
  --user "www-data" \
  --port-range-start 3000 \
  --port-range-end 3010

# Step 5: Restart
hoody daemon stop my-api-server -c my-container
hoody daemon start my-api-server -c my-container

# Step 6: Confirm recovery
hoody daemon status my-api-server -c my-container -o json
```

---

### Advanced Workflow 5: Ephemeral Program for Data Migration

Run a one-time task with automatic cleanup.

```
# Step 1: Launch migration task
hoody daemon start -c my-container -o json \
  --command "python /scripts/migrate_db.py --target production" \
  --user "dbadmin"
# Capture the ephemeral ID from response

# Step 2: Monitor progress via logs
hoody daemon logs <ephemeral-id> -c my-container

# Step 3: Check status periodically
hoody daemon status <ephemeral-id> -c my-container -o json

# Step 4: Stop when complete (auto-removes config)
hoody daemon stop <ephemeral-id> -c my-container
```

**Key difference from persistent programs**: Ephemeral programs are automatically cleaned up on stop or container reboot.

---

## Quick Reference

### Essential Commands

| Command | Purpose |
|---------|---------|
| `hoody daemon health -c <id>` | Check daemon responsiveness |
| `hoody daemon list -c <id>` | List all programs |
| `hoody daemon get <prog-id> -c <id>` | Get program configuration |
| `hoody daemon statuses -c <id>` | Get all runtime statuses |
| `hoody daemon status <prog-id> -c <id>` | Get specific program status |
| `hoody daemon create -c <id>` | Add custom program |
| `hoody daemon edit <prog-id> -c <id>` | Update program config |
| `hoody daemon delete <prog-id> -c <id> --yes` | Remove program permanently |
| `hoody daemon enable <prog-id> -c <id>` | Register with supervisord |
| `hoody daemon disable <prog-id> -c <id>` | Unregister from supervisord |
| `hoody daemon start <prog-id> -c <id>` | Start program |
| `hoody daemon stop <prog-id> -c <id>` | Stop program |
| `hoody daemon reset -c <id>` | Reset to default programs |
| `hoody daemon logs <prog-id> -c <id>` | View program logs |
| `hoody daemon start -c <id>` | Launch ephemeral program |
| `hoody daemon stop <eph-id> -c <id>` | Stop ephemeral program |

### Required Fields for Program Creation

```
{
  "name": "my-program",
  "command": "/usr/bin/node /app/server.js",
  "user": "www-data",
  "port_range": {
    "start": 3000,
    "end": 3010
  }
}
```

### Required Fields for Ephemeral Programs

```
{
  "command": "python /scripts/task.py",
  "user": "app"
}
```

### Port-Range Options

```
# Start specific instance
hoody daemon start <id> -c <container> --port 3001

# Stop specific instance
hoody daemon stop <id> -c <container> --port 3001

# Stop all instances
hoody daemon stop <id> -c <container> --all
```

### Output Format

Append `-o json` to any list/status command for machine-readable output.

### Environment Variables

| Variable | Purpose |
|----------|---------|
| `HOODY_CONTAINER` | Default container ID (replaces `-c` flag) |
| `HOODY_TOKEN` | API authentication token |