API Schema

This page describes the concrete request and response shapes exposed by Runix's current interfaces.

Web REST API

The web dashboard exposes JSON endpoints under /api/v1.

Process Object

Most endpoints return ProcessInfo JSON with this shape:

{
  "id": "abc12345",
  "numeric_id": 1,
  "name": "api",
  "namespace": "backend",
  "instance_index": 0,
  "runtime": "go",
  "state": "running",
  "pid": 48291,
  "exit_code": 0,
  "restarts": 0,
  "created_at": "2026-04-15T20:00:00Z",
  "started_at": "2026-04-15T20:00:01Z",
  "config": {},
  "cpu_percent": 0.4,
  "memory_bytes": 14876672,
  "mem_percent": 0.1,
  "threads": 9,
  "fds": 12,
  "tags": ["api"],
  "uptime": 30000000000
}

Important encoding details:

• state is one of starting, running, stopping, stopped, crashed, errored, waiting
• uptime is serialized as a nanosecond count
• config is the full nested ProcessConfig

GET /api/v1/processes

Response: array of ProcessInfo.

GET /api/v1/processes/{id}

Response: one ProcessInfo.

Not found response:

{
  "error": "process not found"
}

POST /api/v1/processes

Request body: ProcessConfig JSON.

Minimal example:

{
  "name": "api",
  "runtime": "go",
  "entrypoint": "./cmd/api",
  "cwd": "."
}

Success response: created ProcessInfo with HTTP 201.

POST /api/v1/processes/{id}/stop

Query parameters:

Name	Type	Default	Notes
force	bool	false	Sends force-stop behavior
timeout	duration string	5s	Parsed with Go time.ParseDuration

Success response:

{
  "status": "stopped"
}

POST /api/v1/processes/{id}/restart

Success response:

{
  "status": "restarted"
}

POST /api/v1/processes/{id}/reload

Success response:

{
  "status": "reloaded"
}

DELETE /api/v1/processes/{id}

Success response:

{
  "status": "deleted"
}

GET /api/v1/processes/{id}/logs

Query parameters:

Name	Type	Default
lines	integer	50

Success response:

{
  "logs": "last log lines...",
  "path": "api.log",
  "lines": "50"
}

GET /api/v1/system/metrics

Response: system metrics object from internal/metrics. Exact fields depend on the running platform and collector output.

WebSocket Schema

The dashboard listens on /ws and receives process_list messages:

{
  "type": "process_list",
  "processes": [
    {
      "id": "abc12345",
      "numeric_id": 1,
      "name": "api",
      "runtime": "go",
      "state": "running",
      "pid": 48291,
      "exit_code": 0,
      "restarts": 0,
      "cpu_percent": 0.4,
      "memory_bytes": 14876672,
      "mem_percent": 0.1,
      "threads": 9,
      "fds": 12,
      "uptime": 30000000000
    }
  ],
  "timestamp": 1760000000
}

Daemon IPC Schema

The CLI talks to the daemon over HTTP on a Unix socket using a shared envelope.

Request Envelope

{
  "action": "start",
  "payload": {}
}

Response Envelope

{
  "success": true,
  "data": {},
  "error": ""
}

Supported Actions

Action	Payload
start	StartPayload
start_all	StartAllPayload
stop	StopPayload
restart	target string payload handled by daemon
reload	target string payload handled by daemon
delete	target string payload handled by daemon
list	optional empty payload
status	target string payload handled by daemon
logs	LogsPayload
save	optional empty payload
resurrect	optional empty payload
ping	no auth required
cron_list	CronPayload or empty payload
cron_start	CronPayload
cron_stop	CronPayload
cron_run	CronPayload
rolling_reload	RollingReloadPayload
config_reload	ConfigReloadPayload
web_start	WebStartPayload

Named Payload Structs

{
  "name": "api",
  "runtime": "go",
  "entrypoint": "./cmd/api",
  "args": ["--port", "8080"],
  "cwd": ".",
  "env": {"PORT": "8080"},
  "restart_policy": "on-failure",
  "max_restarts": 10
}

The example above is StartPayload.

Other daemon payloads:

Payload	Fields
StartAllPayload	only, config
StopPayload	target, force, timeout, parallel, graceful
LogsPayload	target, lines
CronPayload	name
RollingReloadPayload	target, batch_size, wait_ready, rollback_on_failure
WebStartPayload	listen
ConfigReloadPayload	config_path

MCP Tool Schema

The MCP surface is documented in MCP. Current tool names are:

• list_apps
• start_app
• stop_app
• restart_app
• reload_app
• delete_app
• get_status
• get_logs
• save_state
• resurrect_processes

Current resource URIs are:

• apps://list
• apps://{name}
• logs://{name}
• metrics://{name}

Config Schema

The authoritative configuration structs are documented in:

• Configuration Reference
• Web And Auth Configuration