Action Reference

Runbooks use typed actions. Each has a fixed risk tier, defined parameters, and structured output. No shell execution is allowed — every operation goes through a typed handler.

10 actions are hand-authorable. domain.DefaultActionRegistry() holds ten, so GET /api/v1/runbooks/actions returns ten and the editor's dropdown offers ten.

The agent registers an eleventh, scale_deployment, whenever it is built with a Kubernetes scaler — which the shipped cluster-agent is. It is reachable only through an approved L1 cluster remediation, which persists a client-scoped runbook containing it. You cannot select it in the editor or reference it in a hand-written runbook: it is not in the registry the validator checks against.

Action Summary

Action	Risk	Description
refresh_inventory	read_only	Trigger immediate inventory collection
read_file_tail	read_only	Read the last N lines of a file
read_file_head	read_only	Read the first N lines of a file
restart_systemd_unit	operational	Restart a systemd service
reload_service_config	operational	Reload a systemd service configuration
clear_journal_logs	operational	Vacuum journald logs by age
run_healthcheck	operational	Trigger a Proxima healthcheck run
rotate_log_file	destructive	Copy and truncate a log file
stop_systemd_unit	destructive	Stop a systemd service
kill_process	destructive	Send a signal to a process by name

---

Read-Only Actions

refresh_inventory

Triggers an immediate inventory collection cycle on the agent.

Parameters: None

Returns:

Field	Type	Description
status	string	Always "completed" on success

Example:

- id: refresh
  name: "Refresh host inventory"
  action: refresh_inventory

---

read_file_tail

Reads the last N lines of a file. The file path must match the agent's read allowlist.

Parameters:

Name	Type	Required	Default	Constraints	Description
path	string	Yes	--	Must be absolute, no .., must match read allowlist	File path
lines	int	No	100	min: 1, max: 1000	Number of lines to read

Default read allowlist: /var/log/**, /etc/**, /opt/*/logs/**, /tmp/proxima-*

Returns:

Field	Type	Description
path	string	The file path that was read
lines_read	int	Number of lines actually returned
content	string	The file content

Example:

- id: check_syslog
  name: "Check recent syslog"
  action: read_file_tail
  params:
    path: "/var/log/syslog"
    lines: 50

---

read_file_head

Reads the first N lines of a file. Same allowlist rules as read_file_tail.

Parameters:

Name	Type	Required	Default	Constraints	Description
path	string	Yes	--	Must be absolute, no .., must match read allowlist	File path
lines	int	No	100	min: 1, max: 1000	Number of lines to read

Returns:

Field	Type	Description
path	string	The file path that was read
lines_read	int	Number of lines actually returned
content	string	The file content

Example:

- id: check_config
  name: "Read nginx config header"
  action: read_file_head
  params:
    path: "/etc/nginx/nginx.conf"
    lines: 30

---

Operational Actions

restart_systemd_unit

Restarts a systemd unit and reports its new status.

Parameters:

Name	Type	Required	Constraints	Description
unit	string	Yes	Pattern: ^[a-zA-Z0-9_@][[email protected]]*$	Systemd unit name (e.g., nginx.service)

Returns:

Field	Type	Description
unit	string	The unit name
action	string	"restart"
output	string	systemctl output
status	string	Post-restart status from systemctl is-active

Example:

- id: restart_nginx
  name: "Restart nginx"
  action: restart_systemd_unit
  params:
    unit: nginx.service

---

reload_service_config

Reloads a systemd unit's configuration without a full restart.

Parameters:

Name	Type	Required	Constraints	Description
unit	string	Yes	Pattern: ^[a-zA-Z0-9_@][[email protected]]*$	Systemd unit name

Returns:

Field	Type	Description
unit	string	The unit name
action	string	"reload"
output	string	systemctl output
status	string	Post-reload status from systemctl is-active

Example:

- id: reload_nginx
  name: "Reload nginx config"
  action: reload_service_config
  params:
    unit: nginx.service

---

clear_journal_logs

Vacuums journald logs older than the specified time period.

Parameters:

Name	Type	Required	Allowed Values	Description
vacuum_time	enum	Yes	1d, 3d, 7d, 14d, 30d	Retention period

Returns:

Field	Type	Description
vacuum_time	string	The time period used
output	string	journalctl output (includes freed space)

Example:

- id: clean_logs
  name: "Vacuum journal logs older than 7 days"
  action: clear_journal_logs
  params:
    vacuum_time: "7d"

---

run_healthcheck

Triggers an on-demand Proxima healthcheck run on the agent.

Parameters: None

Returns:

Field	Type	Description
status	string	Always "completed" on success

Example:

- id: healthcheck
  name: "Run healthcheck"
  action: run_healthcheck
  on_failure: warn

---

Destructive Actions

rotate_log_file

Copies the file to {path}.1 and truncates the original to zero bytes. The file path must match the agent's write allowlist.

Parameters:

Name	Type	Required	Constraints	Description
path	string	Yes	Must be absolute, no .., must match write allowlist	Log file path

Default write allowlist: /var/log/**, /opt/*/logs/**

Returns:

Field	Type	Description
path	string	The original file path
old_size_bytes	int	Size of the file before rotation
rotated_to	string	Path of the rotated copy ({path}.1)

Example:

- id: rotate
  name: "Rotate application log"
  action: rotate_log_file
  params:
    path: "/var/log/myapp/access.log"

---

stop_systemd_unit

Stops a systemd unit.

Parameters:

Name	Type	Required	Constraints	Description
unit	string	Yes	Pattern: ^[a-zA-Z0-9_@][[email protected]]*$	Systemd unit name

Returns:

Field	Type	Description
unit	string	The unit name
action	string	"stop"
output	string	systemctl output
status	string	Post-stop status from systemctl is-active

Example:

- id: stop_service
  name: "Stop problematic service"
  action: stop_systemd_unit
  params:
    unit: "{{ service }}"

---

kill_process

Sends a signal to a process identified by exact name match (via pgrep -x, with the name escaped so . is a literal dot). The process must be unambiguous (exactly one PID match), and PID 1 is never signaled.

The name pattern here, and the unit pattern of the systemd actions, are also enforced by the backend: when a runbook is saved (literal values and defaults) and when it is executed (request values). For name the backend is stricter than the agent and refuses any .: agents released before the exact-match fix pass the name to pgrep as a regular expression, where . matches any character. A value built from an earlier step's output can only be checked by the agent.

Parameters:

Name	Type	Required	Default	Constraints	Description
name	string	Yes	--	Pattern enforced by the backend: ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$ (no .). The agent itself accepts ^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$.	Process name
signal	enum	No	SIGTERM	SIGTERM, SIGKILL, SIGHUP, SIGUSR1, SIGUSR2	Signal to send

Protected processes (cannot be killed): init, systemd, sshd, proxima-agent, nats-server

Returns:

Field	Type	Description
name	string	The process name
pid	int	The PID that was signaled
signal	string	The signal that was sent
status	string	"signal_sent"

Example:

- id: kill_worker
  name: "Kill stuck worker process"
  action: kill_process
  params:
    name: myapp-worker
    signal: SIGTERM

---

File Allowlists

File-based actions (read_file_tail, read_file_head, rotate_log_file) enforce path allowlists to prevent unauthorized file access.

Allowlist	Default Patterns	Used By
Read	/var/log/**, /etc/**, /opt/*/logs/**, /tmp/proxima-*	read_file_tail, read_file_head
Write	/var/log/**, /opt/*/logs/**	rotate_log_file

Allowlists can be updated via remote agent configuration. Patterns use glob syntax with ** for recursive directory matching. All paths must be absolute and cannot contain ...

Browsing Actions

The action catalog is available via the API at GET /api/v1/runbooks/actions. This returns the ten registry actions with their parameters and risk tiers (not scale_deployment — see above). The runbook editor uses this endpoint to populate the action dropdown.