# Program Control

**Page:** api/daemon/control

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

---

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



## Program Control

The Program Control API lets you toggle program registration with supervisord and start or stop running processes. Use these endpoints to activate or deactivate programs, and to trigger lifecycle transitions on demand. For port-range programs, individual instances are controlled by specifying a `port`.

---

### Enable a program

`POST /api/v1/daemon/programs/{id}/enable`

Enables the program and registers it with supervisord. Use this to activate a previously disabled program.

#### Parameters

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

This endpoint takes no request body.



```bash
curl -X POST "https://api.hoody.com/api/v1/daemon/programs/1/enable" \
  -H "Authorization: Bearer <token>"
```


```javascript
const result = await client.daemon.control.enable({ id: 1 });
```


```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"
}
```



---

### Disable a program

`POST /api/v1/daemon/programs/{id}/disable`

Disables the program and removes it from supervisord configuration. The program will be stopped if currently running.

#### Parameters

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

This endpoint takes no request body.



```bash
curl -X POST "https://api.hoody.com/api/v1/daemon/programs/1/disable" \
  -H "Authorization: Bearer <token>"
```


```javascript
const result = await client.daemon.control.disable({ id: 1 });
```


```json
{
  "success": true,
  "program": {
    "id": 1,
    "name": "web-server",
    "description": "Nginx web server",
    "enabled": false,
    "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"
}
```



---

### Start a program or port instance

`POST /api/v1/daemon/programs/{id}/start`

Starts the program immediately via supervisorctl. For port-range programs, the `port` parameter is required to specify which instance to start. Set `wait: true` to block until the program reaches the `RUNNING` state. Set `if_not_running: true` for idempotent calls (safe to invoke multiple times) — recommended for Hoody Proxy automation. The program must be enabled.

#### Parameters

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

#### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `port` | integer | No | — | Port number to start (required for port-range programs). Range: 1–65535. |
| `wait` | boolean | No | `false` | Wait for the program to reach `RUNNING` state before returning. |
| `timeout` | integer | No | `30` | Timeout in seconds when `wait` is `true`. Range: 1–300. |
| `if_not_running` | boolean | No | `false` | Only start if not already running (idempotent mode). Returns an `already_running` field in the response. Use this for Hoody Proxy automation. |

**Example: Start specific port instance**
```json
{
  "port": 8042
}
```

**Example: Start and wait for RUNNING state**
```json
{
  "port": 8042,
  "wait": true,
  "timeout": 60
}
```

**Example: Idempotent start (Hoody Proxy usage)**
```json
{
  "port": 8042,
  "if_not_running": true
}
```

**Example: Idempotent start with wait**
```json
{
  "port": 8042,
  "if_not_running": true,
  "wait": true,
  "timeout": 60
}
```



```bash
curl -X POST "https://api.hoody.com/api/v1/daemon/programs/42/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "port": 8042,
    "wait": true,
    "timeout": 60
  }'
```


```javascript
const result = await client.daemon.control.start({
  id: 42,
  data: {
    port: 8042,
    wait: true,
    timeout: 60
  }
});
```


```json
{
  "success": true,
  "instance": {
    "port": 8042,
    "instance_name": "api-server_8042",
    "status": "STARTING"
  }
}
```


```json
{
  "success": true,
  "already_running": true,
  "instance": {
    "port": 8042,
    "instance_name": "api-server_8042",
    "status": "RUNNING",
    "pid": 12345,
    "uptime": "0:15:30"
  }
}
```


```json
{
  "success": true,
  "already_running": false,
  "instance": {
    "port": 8042,
    "instance_name": "api-server_8042",
    "status": "STARTING"
  }
}
```


```json
{
  "success": false,
  "error": "Port parameter is required for port-range programs"
}
```


```json
{
  "success": false,
  "error": "Port must be between 1 and 65535"
}
```


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



---

### Stop a program or port instance

`POST /api/v1/daemon/programs/{id}/stop`

Stops the program immediately via supervisorctl. For port-range programs, specify `port` to stop a specific instance or `all: true` to stop all instances.

#### Parameters

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

#### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `port` | integer | No | — | Specific port instance to stop. Range: 1–65535. |
| `all` | boolean | No | — | Stop all instances (for port-range programs). |

**Example: Stop specific port instance**
```json
{
  "port": 8042
}
```

**Example: Stop all instances**
```json
{
  "all": true
}
```



```bash
curl -X POST "https://api.hoody.com/api/v1/daemon/programs/42/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "port": 8042
  }'
```


```javascript
const result = await client.daemon.control.stop({
  id: 42,
  data: {
    port: 8042
  }
});
```


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


```json
{
  "success": false,
  "error": "Specify either 'port' or 'all: true', not both"
}
```


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




For Hoody Proxy automation, use `if_not_running: true` on the start endpoint to make calls idempotent. This prevents errors when the instance is already running and lets the proxy safely retry ensures-started logic.