From bf6dfe320c08aaf5a2a38a84f5c947eb80b7e4b8 Mon Sep 17 00:00:00 2001 From: "courtmanr@gmail.com" Date: Sun, 26 Jul 2026 19:21:09 +0100 Subject: [PATCH] docs: document container lifecycle actions and the --enable-commands requirement Co-Authored-By: Claude Fable 5 --- docs/DOCKER.md | 19 +++++++++++++++++++ docs/UNIFIED_AGENT.md | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/DOCKER.md b/docs/DOCKER.md index b8e075d109..96499a8185 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -220,6 +220,25 @@ You can also toggle "Hide Docker Update Buttons" from the UI in **Settings → S --- +## ▶️ Container Lifecycle Actions + +Pulse can start, stop, and restart Docker / Podman containers directly from the UI. Running containers offer **stop** and **restart**; stopped containers offer **start**. + +### Requirements + +- **Pulse Agent** installed on the container host (see [Unified Agent](UNIFIED_AGENT.md)) and currently connected +- **Command execution enabled** on the agent — it is disabled by default. Either: + - start the agent with `--enable-commands` (or `PULSE_ENABLE_COMMANDS=true`), or + - tick **Enable Pulse command execution** in **Settings → Infrastructure** before copying the install command, which adds the flag and grants the token the command execution permission +- **Admin approval**: every lifecycle action requires confirmation by an admin in the UI before it runs. The agent then verifies the container's state before the change and confirms it actually reached the requested state afterwards. + +### Limitations + +- If the Docker daemon has **authorization plugins** configured, Pulse blocks all daemon-mutating commands on that host (see advisory GO-2026-4887) and the lifecycle buttons are not offered. Podman hosts are not affected. +- Actions are unavailable while the host's Docker inventory is stale or the agent is disconnected. + +--- + ## 🛠️ Troubleshooting - **Forgot Password?** diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md index adab2e3881..8e7a9ee19b 100644 --- a/docs/UNIFIED_AGENT.md +++ b/docs/UNIFIED_AGENT.md @@ -102,7 +102,7 @@ curl -fsSL http://:7655/install.sh | \ | `--enable-kubernetes` | `PULSE_ENABLE_KUBERNETES` | Enable Kubernetes metrics | `false` (installer auto-detect if not configured) | | `--enable-proxmox` | `PULSE_ENABLE_PROXMOX` | Enable Proxmox integration | `false` | | `--proxmox-type` | `PULSE_PROXMOX_TYPE` | Proxmox type: `pve` or `pbs` | *(auto-detect)* | -| `--enable-commands` | `PULSE_ENABLE_COMMANDS` | Enable AI command execution (disabled by default) | `false` | +| `--enable-commands` | `PULSE_ENABLE_COMMANDS` | Enable Pulse command execution: Docker / Podman container actions from the UI (start/stop/restart/update), Patrol actions, and Proxmox LXC Docker inventory (disabled by default) | `false` | | `--disable-commands` | `PULSE_DISABLE_COMMANDS` | **Deprecated** (commands are disabled by default) | - | | `--disk-exclude` | `PULSE_DISK_EXCLUDE` | Device name/path or mount point patterns to exclude from disk and S.M.A.R.T. monitoring (repeatable or CSV) | *(none)* | | `--kubeconfig` | `PULSE_KUBECONFIG` | Kubeconfig path (optional) | *(auto)* |