Program Control

Use these endpoints to enable, disable, start, and stop daemon programs managed by supervisord. Enable and disable change a program’s registration state — a disabled program is removed from supervisord’s configuration and cannot run. Start and stop control whether an enabled program is currently executing. For programs registered with lazy_load: true, the start endpoint is the call Hoody Proxy makes to bring an instance up on the first incoming request that routes to its port.

Enable and disable

Enable and disable toggle whether supervisord knows about a program at all. Disabling a running program stops it as part of the same call.

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

Response

200

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

404

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

Code example

cURL

curl -X POST "https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com/api/v1/daemon/programs/1/enable" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.daemon.control.enable(1);

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

Response

200

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

404

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

Code example

cURL

curl -X POST "https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com/api/v1/daemon/programs/1/disable" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.daemon.control.disable(1);

Start and stop

Start and stop act on an enabled program immediately via supervisorctl. Port-range programs are multi-instance — each port in the configured range is a separate running process — and these endpoints address one instance at a time unless all: true is sent to stop.

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. The optional wait parameter blocks until the program reaches the RUNNING state, and if_not_running makes the call idempotent.

Note

For a program registered with port_range, this endpoint starts ONE instance and port is required — there is no “start every instance” call. To start a different port, call this endpoint again with a different port value.

Tip

The if_not_running: true flag, paired with wait: true and a timeout (default 30 seconds, operator-configurable), is the exact call Hoody Proxy makes to start a lazy-loaded program on the first request that routes to its port. The lazy_load field itself is documented on the program management page.

Parameters

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

Request Body

Field	Type	Required	Default	Description
port	integer	No (required for port-range programs)	—	Port number to start (required for port-range programs)
wait	boolean	No	false	Wait for program to reach RUNNING state before returning
timeout	integer	No	30	Timeout in seconds when wait=true
if_not_running	boolean	No	false	Only start if not already running (idempotent mode). If true, checks if instance is running first. Returns already_running field in response. Use this for edge proxy automation.

Port-range instance

{
  "port": 8042
}

Port-range with wait

{
  "port": 8042,
  "wait": true,
  "timeout": 60
}

Standard program

{}

Standard with wait

{
  "wait": true,
  "timeout": 30
}

Idempotent (edge proxy)

{
  "port": 8042,
  "if_not_running": true
}

Idempotent + wait

{
  "port": 8042,
  "if_not_running": true,
  "wait": true,
  "timeout": 60
}

Response

200 — started

{
  "success": true,
  "instance": {
    "port": 8042,
    "instance_name": "api-server_8042",
    "status": "starting"
  }
}

200 — idempotent already running

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

200 — idempotent just started

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

400 — port required

{
  "success": false,
  "error": "port is required for port-range program \"api-server\""
}

400 — port out of range

{
  "success": false,
  "error": "port 70000 is outside the configured range 8000-8099"
}

404

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

Code example

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.daemon.control.start(1, { port: 8042, wait: true, timeout: 60 });

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 every instance.

Parameters

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

Request Body

Field	Type	Required	Default	Description
port	integer	No	—	Specific port to stop
all	boolean	No	—	Stop all instances (for port-range programs)

Stop specific port

{
  "port": 8042
}

Stop all instances

{
  "all": true
}

Standard program

{}

Response

200

{
  "success": true
}

400

{
  "success": false,
  "error": "Provide either \"port\" or \"all: true\" for a port-range program, not both"
}

404

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

Code example

cURL

curl -X POST "https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com/api/v1/daemon/programs/1/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-daemon-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.daemon.control.stop(1, { all: true });