Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Make agent profile guidance match authority and application boundaries
pulse-triage[bot]edfa6ae1d38d
diff --git a/.github/workflows/public-docs.yml b/.github/workflows/public-docs.ymlindex c7a38e55fe..6fd4583567 100644--- a/.github/workflows/public-docs.yml+++ b/.github/workflows/public-docs.yml@@ -14,6 +14,7 @@ on:- "scripts/tests/test_public_docs_workflow.py"- "scripts/tests/test_production_rollout_docs.py"- "scripts/tests/test_pmg_docs.py"+ - "scripts/tests/test_agent_profile_docs.py"- "scripts/tests/test_pve_backup_troubleshooting_docs.py"- "scripts/tests/test_vm_disk_diagnostics.py"- "scripts/tests/test_memory_troubleshooting_docs.py"@@ -36,6 +37,7 @@ on:- "scripts/tests/test_public_docs_workflow.py"- "scripts/tests/test_production_rollout_docs.py"- "scripts/tests/test_pmg_docs.py"+ - "scripts/tests/test_agent_profile_docs.py"- "scripts/tests/test_pve_backup_troubleshooting_docs.py"- "scripts/tests/test_vm_disk_diagnostics.py"- "scripts/tests/test_memory_troubleshooting_docs.py"@@ -81,6 +83,7 @@ jobs:scripts/tests/run.sh \test_production_rollout_docs.py \test_pmg_docs.py \+ test_agent_profile_docs.py \test_pve_backup_troubleshooting_docs.py \test_vm_disk_diagnostics.py \test_memory_troubleshooting_docs.py \diff --git a/docs/CENTRALIZED_MANAGEMENT.md b/docs/CENTRALIZED_MANAGEMENT.mdindex da1c907309..5874f32832 100644--- a/docs/CENTRALIZED_MANAGEMENT.md+++ b/docs/CENTRALIZED_MANAGEMENT.md@@ -1,190 +1,207 @@# Centralized Agent Management (Pro/legacy Pro+/Cloud)-Pro, legacy Pro+, and Cloud support centralized management of `pulse-agent` configurations, allowing administrators to define "Configuration Profiles" and assign them to specific installed agents. This enables bulk updates and consistent configuration across your fleet without manually editing configuration files on each host.+Agent profiles let an administrator save supported `pulse-agent` settings and+assign them to installed agents. They are configuration, not an installer,+credential rotation, command-authority grant or proof of fleet-wide deployment.+The `agent_profiles` licence capability is required.-Profiles are managed in the UI from **Settings → Infrastructure → Install on a host → Manage agent profiles**.+Open **Settings → Infrastructure → Install on a host → Manage agent profiles**.+Keep the selected organisation and agent identity consistent throughout; an+agent's displayed hostname is not its unique Agent ID.## Concepts-- **Agent Profile**: A named collection of configuration settings (e.g., "Production Servers", "Debug Mode").-- **Assignment**: A link between a specific Agent ID and an Agent Profile.-- **Precedence**: Server-side profile settings override local agent flags/environment for supported keys, except for explicit local privacy opt-outs.+- **Profile**: a named configuration, optionally inheriting from a parent profile.+- **Assignment**: the link from an existing Agent ID to a profile's actual `id`.+ Assigning a different profile replaces that agent's previous assignment.+- **Precedence**: on a successful startup fetch, supported profile keys override+ local flags/environment, except explicit local privacy opt-outs. A local+ `--enable-docker=false` or `PULSE_ENABLE_DOCKER=false` remains a hard opt-out;+ a profile cannot turn Docker/Podman collection back on.## Supported Configuration Keys-The following settings can be controlled remotely via profiles:+Read **schema** on your running server for its supported keys and validation.+The following keys are applied at agent startup; the three host settings marked+below also support live refresh when the host module is running:| Key | Type | Description |-| :--- | :--- | :--- |-| `interval` | string | Set reporting interval (e.g., "30s", "1m") |-| `enable_host` | boolean | Enable/Disable host monitoring (metrics + command execution) |-| `enable_docker` | boolean | Enable/Disable Docker / Podman monitoring |-| `enable_kubernetes` | boolean | Enable/Disable Kubernetes monitoring |-| `enable_proxmox` | boolean | Enable/Disable Proxmox monitoring |-| `proxmox_type` | string | Set Proxmox type (`pve`, `pbs`, or `auto`) |-| `docker_runtime` | string | Docker / Podman runtime preference (`auto`, `docker`, `podman`) |+| --- | --- | --- |+| `interval` | duration | Reporting interval, for example `30s` or `1m`; also refreshed live for the host module |+| `enable_host` | boolean | Host metrics collection only; does not grant command execution |+| `enable_docker` | boolean | Docker/Podman monitoring, subject to the local opt-out |+| `enable_kubernetes` | boolean | Kubernetes monitoring |+| `enable_proxmox` | boolean | Proxmox monitoring |+| `proxmox_type` | enum | `pve`, `pbs` or `auto` |+| `docker_runtime` | enum | `auto`, `docker` or `podman` || `disable_auto_update` | boolean | Disable automatic agent updates || `disable_docker_update_checks` | boolean | Disable Docker image update detection |-| `kube_include_all_pods` | boolean | Include all non-succeeded pods in Kubernetes reports |-| `kube_include_all_deployments` | boolean | Include all deployments in Kubernetes reports |-| `log_level` | string | Set agent log level (`debug`, `info`, `warn`, `error`) |-| `report_ip` | string | Override the reported IP address for the agent |-| `disable_ceph` | boolean | Disable local Ceph status polling |--Notes:-- `interval` accepts a duration string. If you send a JSON number, it is interpreted as seconds.-- Docker auto-detection can still enable Docker monitoring if the agent is not explicitly configured. To force-disable Docker, set `PULSE_ENABLE_DOCKER=false` or install with `--enable-docker=false` on the host. That local disable also blocks remote profiles from turning Docker/Podman monitoring back on.-- `commandsEnabled` (AI command execution) is controlled separately per agent from the Infrastructure agent controls and is applied live on report. It is not part of profile settings.+| `kube_include_all_pods` | boolean | Include all non-succeeded Kubernetes pods |+| `kube_include_all_deployments` | boolean | Include all Kubernetes deployments |+| `log_level` | enum | `debug`, `info`, `warn` or `error` |+| `report_ip` | string | Reported host IP override; also refreshed live for the host module |+| `disable_ceph` | boolean | Disable local Ceph polling; also refreshed live for the host module |++`interval` accepts a positive duration string; JSON numbers are interpreted as+seconds. Do not enable Debug, shorten intervals or change monitoring scope just+to collect a report. Use the [bounded agent log readers](UNIFIED_AGENT.md#collect-agent-logs-safely)+and evidence already available.++### Monitoring is not command authority++`enable_host` controls metrics, not AI or container actions. `commandsEnabled`+is a separate per-agent control, not a profile key. Command use also depends on+the installed local authority, the token's `agent:exec` scope and its permitted+agent binding. A monitoring-only runtime rejects remote command enablement;+changing a profile or adding a token scope cannot promote that runtime.++Leave commands off for monitoring. Do not enable them, reinstall with broader+privileges or replace the token to fix missing metrics. A switch saved on the+server is not proof of an admitted command channel. See+[Agent Security](AGENT_SECURITY.md) and+[blocked remote control](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked)+for the separate authority checks.++## Safe profile rollout++1. Read the current profile, assignment and local opt-outs before changing them.+ Retain the previous configuration privately. A shared profile change affects+ every agent assigned to it, including agents inheriting it through a parent.+2. Validate the intended configuration without saving. Validation checks keys+ and values, not host permissions, installed modules, connectivity or workload+ safety. Use one suitable non-production agent before widening a rollout.+3. Save the intended profile and assign it using the returned profile `id` and+ the existing agent's canonical Agent ID, not a guessed name or machine ID.+ Read back both records after saving.+4. Observe normal config fetches and fresh reports from each affected agent.+ A saved profile, deployment-status row or successful config response is not+ proof that every setting was applied or that readings recovered.+5. For startup-only keys, arrange an agent restart through its existing+ deployment during a suitable maintenance window, preserving its image,+ credentials and state. Do not restart, re-enrol or change a host identity+ just to diagnose a missing reading. Monitoring is interrupted during restart;+ arrange independent coverage where needed.++### When settings take effect++The agent fetches configuration on startup. With the host module running,+current agents also refresh about once a minute. The host module can apply+`interval`, `report_ip` and `disable_ceph` without restarting. Other profile+keys, including module enablement, runtime choice, log level and auto-update+settings, require a successful startup fetch; a refresh is not an all-module+live reload. `commandsEnabled` can change live, within the separate authority+boundary above.++An existing process keeps its current settings if a refresh fails. A failed+startup fetch can leave the agent using local settings. A timeout, rejected+signature or authentication failure is not proof of rollback, revocation or+successful application. Preserve the error and use the normal fetch/report+observations; do not disable signature or TLS verification to make it pass.++Unassigning or deleting a profile does not undo settings already applied to a+running process, revoke its token, stop monitoring or revoke command authority.+Rollback restores the selected historical profile content as a **new version**;+it still needs the same fetch/application checks on every affected agent.+Unassignment is not an emergency stop. If collection must stop, use the+established local service procedure rather than relying on a saved assignment;+keep independent monitoring and incident recovery separate.## API Usage-All endpoints require **Admin** authentication and a Pro, legacy Pro+, or Cloud license.--### 1. Create a Profile--```http-POST /api/admin/profiles/-Authorization: Bearer <admin-token>-Content-Type: application/json+Prefer the signed-in UI for changes. Profile endpoints require administrator+access, `settings:write` token scope and the `agent_profiles` licence capability,+even for profile reads. An agent reporting token is not a profile-management+credential. Keep the current organisation selected; a denied request is not a+reason to grant unrelated scopes or bypass authentication.++For a read-only API check, prepare the private header file and define `pulse_api`+**in the same Bash session** using [API authentication](API.md#-authentication).+That helper is local example code, not an installed Pulse command. On the Pulse+host it uses loopback with bounded curl requests; use the guide's verified HTTPS+origin for remote access. It saves responses privately, with no redirects or+automatic retries. Never paste a token or session cookie into a command, URL or+thread, or use browser **Copy as cURL**.++```bash+# Read only the records relevant to this change+pulse_api GET /api/admin/profiles/schema+pulse_api GET /api/admin/profiles/+pulse_api GET /api/admin/profiles/assignments+```+Open saved responses locally: profiles, assignments, IP overrides and errors+can reveal infrastructure identities. Share only a relevant manually redacted+excerpt, not full responses, headers, configuration files or tokens. HTTP+401/402/403, redirects and transport errors are not an empty profile list.++### Endpoint reference++These paths describe existing operations; do not run every operation as a+diagnostic checklist. Replace `{id}`, `{agent_id}` and `{version}` with values+from the current instance. Use the UI or an authenticated client that reads+credentials and request bodies from private files, preserves CSRF protection+for session writes and verifies HTTPS. The example `pulse_api` helper supports+GET and POST only, not PUT or DELETE.++| Method | Path | Purpose |+| --- | --- | --- |+| GET | `/api/admin/profiles/` | List profiles |+| POST | `/api/admin/profiles/` | Create a profile; returns its generated UUID `id` and version 1 |+| GET / PUT / DELETE | `/api/admin/profiles/{id}` | Read, replace or delete a profile |+| GET / POST | `/api/admin/profiles/assignments` | Read or replace assignments |+| DELETE | `/api/admin/profiles/assignments/{agent_id}` | Unassign a profile; not token or command revocation |+| GET | `/api/admin/profiles/schema` | Supported configuration keys |+| POST | `/api/admin/profiles/validate` | Validate without saving |+| POST | `/api/admin/profiles/suggestions` | Optional AI suggestion; may call the configured AI provider, not a read-only diagnostic |+| GET | `/api/admin/profiles/{id}/versions` | Profile version history |+| POST | `/api/admin/profiles/{id}/rollback/{version}` | Restore historical content as a new version |+| GET | `/api/admin/profiles/changelog` | Recorded profile changes |+| GET / POST | `/api/admin/profiles/deployments` | Read or record deployment status; not independent host acceptance |++Example **request bodies**, not credential-bearing HTTP commands:++```json{"name": "Production Servers",- "config": {- "enable_docker": true,- "log_level": "info",- "interval": "60s"- }+ "config": {"enable_docker": true, "log_level": "info", "interval": "60s"}}```-### 2. Assign Profile to Agent--You need the Agent ID (typically the machine ID, visible in the Pulse UI or agent logs).--```http-POST /api/admin/profiles/assignments-Authorization: Bearer <admin-token>-Content-Type: application/json+For validation, send only `{"config": {...}}`. For assignment, use the actual+`id` returned by creation or the profile list, not `prod-servers`:+```json{- "agent_id": "01234567-89ab-cdef-0123-456789abcdef",- "profile_id": "prod-servers"+ "agent_id": "<existing-canonical-agent-id>",+ "profile_id": "<returned-profile-uuid>"}```-### 3. List Profiles--```http-GET /api/admin/profiles/-Authorization: Bearer <admin-token>-```--### 4. List Assignments--```http-GET /api/admin/profiles/assignments-Authorization: Bearer <admin-token>-```--### 5. Unassign Profile--```http-DELETE /api/admin/profiles/assignments/{agent_id}-Authorization: Bearer <admin-token>-```--### 6. Get Agent Config (Debugging)--To see what configuration an agent receives:--```http-GET /api/agents/agent/{agent_id}/config-Authorization: Bearer <agent-or-admin-token>-```--Requires `agent:config:read` (or admin tokens with management scopes).--### 7. Schema, Validation, and Suggestions--Use the schema endpoint to see supported keys and types, and validate configs before saving:--```http-GET /api/admin/profiles/schema-Authorization: Bearer <admin-token>-```--```http-POST /api/admin/profiles/validate-Authorization: Bearer <admin-token>-Content-Type: application/json+After an uncertain create, update, assignment, rollback or deletion, read the+current profile, assignment and version before considering another write. The+server may already have saved it despite a lost response. Do not blindly repeat+POST, delete configuration files, recreate profiles or clear history to make a+failed banner disappear. Creation/readback alone does not establish delivery.-{- "config": {- "interval": "60s",- "enable_docker": true- }-}-```--Optional AI suggestions:--```http-POST /api/admin/profiles/suggestions-Authorization: Bearer <admin-token>-Content-Type: application/json-```--### 8. Version History and Rollback--Each profile update increments its version and is stored in `profile-versions.json`.--```http-GET /api/admin/profiles/{id}/versions-Authorization: Bearer <admin-token>-```--Rollback to a specific version:--```http-POST /api/admin/profiles/{id}/rollback/{version}-Authorization: Bearer <admin-token>-```--### 9. Change Log and Deployment Status--Change log entries are stored in `profile-changelog.json`:--```http-GET /api/admin/profiles/changelog-Authorization: Bearer <admin-token>-```--Deployment status is stored in `profile-deployments.json`:--```http-GET /api/admin/profiles/deployments-Authorization: Bearer <admin-token>-```--Update deployment status via:--```http-POST /api/admin/profiles/deployments-Authorization: Bearer <admin-token>-Content-Type: application/json-```+### Reading an agent's desired configuration-## Agent Behavior+`GET /api/agents/agent/{agent_id}/config` uses a separate credential path:+`agent:config:read` or a compatible existing agent token is restricted by token+binding; `agent:manage` or `settings:write` allows management reads. Use the+appropriate existing credential, never give an agent an administrator token to+work around a denial. The response names the resolved `agentId`; compare it+with the intended canonical agent before interpreting its settings.-1. On startup, the agent computes its Agent ID.-2. It contacts the Pulse server to fetch its configuration profile.-3. If successful, it applies the remote settings, overriding local flags/env for supported keys.-4. If the server is unreachable or returns an error, the agent proceeds with its local configuration.-5. Profile changes take effect on the next agent restart. Command execution toggles are applied dynamically.+This response is the server's **desired configuration**, not an observation of+what the process applied. It can contain private settings and signed metadata;+keep it private. A 404 can mean the agent has not registered, not that a profile+was deleted. Config-signature validation and live readings remain separate+checks; do not re-enrol or reset an agent just to obtain this response.## Storage-Profiles and assignments are stored in the Pulse config directory:+Profiles and assignments live in the selected organisation's Pulse config+storage, not on each monitored host:- `agent_profiles.json`- `agent_profile_assignments.json`@@ -192,4 +209,8 @@ Profiles and assignments are stored in the Pulse config directory:- `profile-changelog.json`- `profile-deployments.json`-Deleting a profile automatically removes its assignments.+Deleting a profile removes its direct assignments in server storage; it does+not remove local credentials or provide a verified rollback on remote hosts.+Keep configuration, history and consistent private backups intact during+investigation. See [configuration transfer](MIGRATION.md#configuration-transfer)+for what a backup actually includes.diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex ac61a2ea77..201e12ef91 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -857,7 +857,13 @@ Pro, legacy Pro+, and Cloud can push centralized settings to agents via Agent PrBehavior:- The agent fetches remote config on startup from `/api/agents/agent/{agent_id}/config`.- Profile settings override local flags/env for supported keys.-- Profile changes take effect on the next agent restart.+- With the host module running, current agents refresh about once a minute.+ Host `interval`, `report_ip` and `disable_ceph` settings can apply live; other+ profile keys require a successful startup fetch. A refresh is not an+ all-module live reload, and a saved assignment is not applied-state proof.+- Removing an assignment does not undo settings already applied to a running+ process, revoke its token or stop monitoring. Keep incident recovery separate+ from profile rollout; do not restart or re-enrol solely to diagnose a reading.- Command execution (`commandsEnabled`) is controlled per agent from the Infrastructure agent controls and can change live.- Remote config responses can be signed with `PULSE_AGENT_CONFIG_SIGNING_KEY` (base64 Ed25519 private key).- To require signed payloads, set `PULSE_AGENT_CONFIG_SIGNATURE_REQUIRED=true` on Pulse and agents.diff --git a/frontend-modern/public/docs/CENTRALIZED_MANAGEMENT.md b/frontend-modern/public/docs/CENTRALIZED_MANAGEMENT.mdindex da1c907309..5874f32832 100644--- a/frontend-modern/public/docs/CENTRALIZED_MANAGEMENT.md+++ b/frontend-modern/public/docs/CENTRALIZED_MANAGEMENT.md@@ -1,190 +1,207 @@# Centralized Agent Management (Pro/legacy Pro+/Cloud)-Pro, legacy Pro+, and Cloud support centralized management of `pulse-agent` configurations, allowing administrators to define "Configuration Profiles" and assign them to specific installed agents. This enables bulk updates and consistent configuration across your fleet without manually editing configuration files on each host.+Agent profiles let an administrator save supported `pulse-agent` settings and+assign them to installed agents. They are configuration, not an installer,+credential rotation, command-authority grant or proof of fleet-wide deployment.+The `agent_profiles` licence capability is required.-Profiles are managed in the UI from **Settings → Infrastructure → Install on a host → Manage agent profiles**.+Open **Settings → Infrastructure → Install on a host → Manage agent profiles**.+Keep the selected organisation and agent identity consistent throughout; an+agent's displayed hostname is not its unique Agent ID.## Concepts-- **Agent Profile**: A named collection of configuration settings (e.g., "Production Servers", "Debug Mode").-- **Assignment**: A link between a specific Agent ID and an Agent Profile.-- **Precedence**: Server-side profile settings override local agent flags/environment for supported keys, except for explicit local privacy opt-outs.+- **Profile**: a named configuration, optionally inheriting from a parent profile.+- **Assignment**: the link from an existing Agent ID to a profile's actual `id`.+ Assigning a different profile replaces that agent's previous assignment.+- **Precedence**: on a successful startup fetch, supported profile keys override+ local flags/environment, except explicit local privacy opt-outs. A local+ `--enable-docker=false` or `PULSE_ENABLE_DOCKER=false` remains a hard opt-out;+ a profile cannot turn Docker/Podman collection back on.## Supported Configuration Keys-The following settings can be controlled remotely via profiles:+Read **schema** on your running server for its supported keys and validation.+The following keys are applied at agent startup; the three host settings marked+below also support live refresh when the host module is running:| Key | Type | Description |-| :--- | :--- | :--- |-| `interval` | string | Set reporting interval (e.g., "30s", "1m") |-| `enable_host` | boolean | Enable/Disable host monitoring (metrics + command execution) |-| `enable_docker` | boolean | Enable/Disable Docker / Podman monitoring |-| `enable_kubernetes` | boolean | Enable/Disable Kubernetes monitoring |-| `enable_proxmox` | boolean | Enable/Disable Proxmox monitoring |-| `proxmox_type` | string | Set Proxmox type (`pve`, `pbs`, or `auto`) |-| `docker_runtime` | string | Docker / Podman runtime preference (`auto`, `docker`, `podman`) |+| --- | --- | --- |+| `interval` | duration | Reporting interval, for example `30s` or `1m`; also refreshed live for the host module |+| `enable_host` | boolean | Host metrics collection only; does not grant command execution |+| `enable_docker` | boolean | Docker/Podman monitoring, subject to the local opt-out |+| `enable_kubernetes` | boolean | Kubernetes monitoring |+| `enable_proxmox` | boolean | Proxmox monitoring |+| `proxmox_type` | enum | `pve`, `pbs` or `auto` |+| `docker_runtime` | enum | `auto`, `docker` or `podman` || `disable_auto_update` | boolean | Disable automatic agent updates || `disable_docker_update_checks` | boolean | Disable Docker image update detection |-| `kube_include_all_pods` | boolean | Include all non-succeeded pods in Kubernetes reports |-| `kube_include_all_deployments` | boolean | Include all deployments in Kubernetes reports |-| `log_level` | string | Set agent log level (`debug`, `info`, `warn`, `error`) |-| `report_ip` | string | Override the reported IP address for the agent |-| `disable_ceph` | boolean | Disable local Ceph status polling |--Notes:-- `interval` accepts a duration string. If you send a JSON number, it is interpreted as seconds.-- Docker auto-detection can still enable Docker monitoring if the agent is not explicitly configured. To force-disable Docker, set `PULSE_ENABLE_DOCKER=false` or install with `--enable-docker=false` on the host. That local disable also blocks remote profiles from turning Docker/Podman monitoring back on.-- `commandsEnabled` (AI command execution) is controlled separately per agent from the Infrastructure agent controls and is applied live on report. It is not part of profile settings.+| `kube_include_all_pods` | boolean | Include all non-succeeded Kubernetes pods |+| `kube_include_all_deployments` | boolean | Include all Kubernetes deployments |+| `log_level` | enum | `debug`, `info`, `warn` or `error` |+| `report_ip` | string | Reported host IP override; also refreshed live for the host module |+| `disable_ceph` | boolean | Disable local Ceph polling; also refreshed live for the host module |++`interval` accepts a positive duration string; JSON numbers are interpreted as+seconds. Do not enable Debug, shorten intervals or change monitoring scope just+to collect a report. Use the [bounded agent log readers](UNIFIED_AGENT.md#collect-agent-logs-safely)+and evidence already available.++### Monitoring is not command authority++`enable_host` controls metrics, not AI or container actions. `commandsEnabled`+is a separate per-agent control, not a profile key. Command use also depends on+the installed local authority, the token's `agent:exec` scope and its permitted+agent binding. A monitoring-only runtime rejects remote command enablement;+changing a profile or adding a token scope cannot promote that runtime.++Leave commands off for monitoring. Do not enable them, reinstall with broader+privileges or replace the token to fix missing metrics. A switch saved on the+server is not proof of an admitted command channel. See+[Agent Security](AGENT_SECURITY.md) and+[blocked remote control](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked)+for the separate authority checks.++## Safe profile rollout++1. Read the current profile, assignment and local opt-outs before changing them.+ Retain the previous configuration privately. A shared profile change affects+ every agent assigned to it, including agents inheriting it through a parent.+2. Validate the intended configuration without saving. Validation checks keys+ and values, not host permissions, installed modules, connectivity or workload+ safety. Use one suitable non-production agent before widening a rollout.+3. Save the intended profile and assign it using the returned profile `id` and+ the existing agent's canonical Agent ID, not a guessed name or machine ID.+ Read back both records after saving.+4. Observe normal config fetches and fresh reports from each affected agent.+ A saved profile, deployment-status row or successful config response is not+ proof that every setting was applied or that readings recovered.+5. For startup-only keys, arrange an agent restart through its existing+ deployment during a suitable maintenance window, preserving its image,+ credentials and state. Do not restart, re-enrol or change a host identity+ just to diagnose a missing reading. Monitoring is interrupted during restart;+ arrange independent coverage where needed.++### When settings take effect++The agent fetches configuration on startup. With the host module running,+current agents also refresh about once a minute. The host module can apply+`interval`, `report_ip` and `disable_ceph` without restarting. Other profile+keys, including module enablement, runtime choice, log level and auto-update+settings, require a successful startup fetch; a refresh is not an all-module+live reload. `commandsEnabled` can change live, within the separate authority+boundary above.++An existing process keeps its current settings if a refresh fails. A failed+startup fetch can leave the agent using local settings. A timeout, rejected+signature or authentication failure is not proof of rollback, revocation or+successful application. Preserve the error and use the normal fetch/report+observations; do not disable signature or TLS verification to make it pass.++Unassigning or deleting a profile does not undo settings already applied to a+running process, revoke its token, stop monitoring or revoke command authority.+Rollback restores the selected historical profile content as a **new version**;+it still needs the same fetch/application checks on every affected agent.+Unassignment is not an emergency stop. If collection must stop, use the+established local service procedure rather than relying on a saved assignment;+keep independent monitoring and incident recovery separate.## API Usage-All endpoints require **Admin** authentication and a Pro, legacy Pro+, or Cloud license.--### 1. Create a Profile--```http-POST /api/admin/profiles/-Authorization: Bearer <admin-token>-Content-Type: application/json+Prefer the signed-in UI for changes. Profile endpoints require administrator+access, `settings:write` token scope and the `agent_profiles` licence capability,+even for profile reads. An agent reporting token is not a profile-management+credential. Keep the current organisation selected; a denied request is not a+reason to grant unrelated scopes or bypass authentication.++For a read-only API check, prepare the private header file and define `pulse_api`+**in the same Bash session** using [API authentication](API.md#-authentication).+That helper is local example code, not an installed Pulse command. On the Pulse+host it uses loopback with bounded curl requests; use the guide's verified HTTPS+origin for remote access. It saves responses privately, with no redirects or+automatic retries. Never paste a token or session cookie into a command, URL or+thread, or use browser **Copy as cURL**.++```bash+# Read only the records relevant to this change+pulse_api GET /api/admin/profiles/schema+pulse_api GET /api/admin/profiles/+pulse_api GET /api/admin/profiles/assignments+```+Open saved responses locally: profiles, assignments, IP overrides and errors+can reveal infrastructure identities. Share only a relevant manually redacted+excerpt, not full responses, headers, configuration files or tokens. HTTP+401/402/403, redirects and transport errors are not an empty profile list.++### Endpoint reference++These paths describe existing operations; do not run every operation as a+diagnostic checklist. Replace `{id}`, `{agent_id}` and `{version}` with values+from the current instance. Use the UI or an authenticated client that reads+credentials and request bodies from private files, preserves CSRF protection+for session writes and verifies HTTPS. The example `pulse_api` helper supports+GET and POST only, not PUT or DELETE.++| Method | Path | Purpose |+| --- | --- | --- |+| GET | `/api/admin/profiles/` | List profiles |+| POST | `/api/admin/profiles/` | Create a profile; returns its generated UUID `id` and version 1 |+| GET / PUT / DELETE | `/api/admin/profiles/{id}` | Read, replace or delete a profile |+| GET / POST | `/api/admin/profiles/assignments` | Read or replace assignments |+| DELETE | `/api/admin/profiles/assignments/{agent_id}` | Unassign a profile; not token or command revocation |+| GET | `/api/admin/profiles/schema` | Supported configuration keys |+| POST | `/api/admin/profiles/validate` | Validate without saving |+| POST | `/api/admin/profiles/suggestions` | Optional AI suggestion; may call the configured AI provider, not a read-only diagnostic |+| GET | `/api/admin/profiles/{id}/versions` | Profile version history |+| POST | `/api/admin/profiles/{id}/rollback/{version}` | Restore historical content as a new version |+| GET | `/api/admin/profiles/changelog` | Recorded profile changes |+| GET / POST | `/api/admin/profiles/deployments` | Read or record deployment status; not independent host acceptance |++Example **request bodies**, not credential-bearing HTTP commands:++```json{"name": "Production Servers",- "config": {- "enable_docker": true,- "log_level": "info",- "interval": "60s"- }+ "config": {"enable_docker": true, "log_level": "info", "interval": "60s"}}```-### 2. Assign Profile to Agent--You need the Agent ID (typically the machine ID, visible in the Pulse UI or agent logs).--```http-POST /api/admin/profiles/assignments-Authorization: Bearer <admin-token>-Content-Type: application/json+For validation, send only `{"config": {...}}`. For assignment, use the actual+`id` returned by creation or the profile list, not `prod-servers`:+```json{- "agent_id": "01234567-89ab-cdef-0123-456789abcdef",- "profile_id": "prod-servers"+ "agent_id": "<existing-canonical-agent-id>",+ "profile_id": "<returned-profile-uuid>"}```-### 3. List Profiles--```http-GET /api/admin/profiles/-Authorization: Bearer <admin-token>-```--### 4. List Assignments--```http-GET /api/admin/profiles/assignments-Authorization: Bearer <admin-token>-```--### 5. Unassign Profile--```http-DELETE /api/admin/profiles/assignments/{agent_id}-Authorization: Bearer <admin-token>-```--### 6. Get Agent Config (Debugging)--To see what configuration an agent receives:--```http-GET /api/agents/agent/{agent_id}/config-Authorization: Bearer <agent-or-admin-token>-```--Requires `agent:config:read` (or admin tokens with management scopes).--### 7. Schema, Validation, and Suggestions--Use the schema endpoint to see supported keys and types, and validate configs before saving:--```http-GET /api/admin/profiles/schema-Authorization: Bearer <admin-token>-```--```http-POST /api/admin/profiles/validate-Authorization: Bearer <admin-token>-Content-Type: application/json+After an uncertain create, update, assignment, rollback or deletion, read the+current profile, assignment and version before considering another write. The+server may already have saved it despite a lost response. Do not blindly repeat+POST, delete configuration files, recreate profiles or clear history to make a+failed banner disappear. Creation/readback alone does not establish delivery.-{- "config": {- "interval": "60s",- "enable_docker": true- }-}-```--Optional AI suggestions:--```http-POST /api/admin/profiles/suggestions-Authorization: Bearer <admin-token>-Content-Type: application/json-```--### 8. Version History and Rollback--Each profile update increments its version and is stored in `profile-versions.json`.--```http-GET /api/admin/profiles/{id}/versions-Authorization: Bearer <admin-token>-```--Rollback to a specific version:--```http-POST /api/admin/profiles/{id}/rollback/{version}-Authorization: Bearer <admin-token>-```--### 9. Change Log and Deployment Status--Change log entries are stored in `profile-changelog.json`:--```http-GET /api/admin/profiles/changelog-Authorization: Bearer <admin-token>-```--Deployment status is stored in `profile-deployments.json`:--```http-GET /api/admin/profiles/deployments-Authorization: Bearer <admin-token>-```--Update deployment status via:--```http-POST /api/admin/profiles/deployments-Authorization: Bearer <admin-token>-Content-Type: application/json-```+### Reading an agent's desired configuration-## Agent Behavior+`GET /api/agents/agent/{agent_id}/config` uses a separate credential path:+`agent:config:read` or a compatible existing agent token is restricted by token+binding; `agent:manage` or `settings:write` allows management reads. Use the+appropriate existing credential, never give an agent an administrator token to+work around a denial. The response names the resolved `agentId`; compare it+with the intended canonical agent before interpreting its settings.-1. On startup, the agent computes its Agent ID.-2. It contacts the Pulse server to fetch its configuration profile.-3. If successful, it applies the remote settings, overriding local flags/env for supported keys.-4. If the server is unreachable or returns an error, the agent proceeds with its local configuration.-5. Profile changes take effect on the next agent restart. Command execution toggles are applied dynamically.+This response is the server's **desired configuration**, not an observation of+what the process applied. It can contain private settings and signed metadata;+keep it private. A 404 can mean the agent has not registered, not that a profile+was deleted. Config-signature validation and live readings remain separate+checks; do not re-enrol or reset an agent just to obtain this response.## Storage-Profiles and assignments are stored in the Pulse config directory:+Profiles and assignments live in the selected organisation's Pulse config+storage, not on each monitored host:- `agent_profiles.json`- `agent_profile_assignments.json`@@ -192,4 +209,8 @@ Profiles and assignments are stored in the Pulse config directory:- `profile-changelog.json`- `profile-deployments.json`-Deleting a profile automatically removes its assignments.+Deleting a profile removes its direct assignments in server storage; it does+not remove local credentials or provide a verified rollback on remote hosts.+Keep configuration, history and consistent private backups intact during+investigation. See [configuration transfer](MIGRATION.md#configuration-transfer)+for what a backup actually includes.diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex ac61a2ea77..201e12ef91 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -857,7 +857,13 @@ Pro, legacy Pro+, and Cloud can push centralized settings to agents via Agent PrBehavior:- The agent fetches remote config on startup from `/api/agents/agent/{agent_id}/config`.- Profile settings override local flags/env for supported keys.-- Profile changes take effect on the next agent restart.+- With the host module running, current agents refresh about once a minute.+ Host `interval`, `report_ip` and `disable_ceph` settings can apply live; other+ profile keys require a successful startup fetch. A refresh is not an+ all-module live reload, and a saved assignment is not applied-state proof.+- Removing an assignment does not undo settings already applied to a running+ process, revoke its token or stop monitoring. Keep incident recovery separate+ from profile rollout; do not restart or re-enrol solely to diagnose a reading.- Command execution (`commandsEnabled`) is controlled per agent from the Infrastructure agent controls and can change live.- Remote config responses can be signed with `PULSE_AGENT_CONFIG_SIGNING_KEY` (base64 Ed25519 private key).- To require signed payloads, set `PULSE_AGENT_CONFIG_SIGNATURE_REQUIRED=true` on Pulse and agents.diff --git a/scripts/tests/test_agent_profile_docs.py b/scripts/tests/test_agent_profile_docs.pynew file mode 100644index 0000000000..d8a3ee3a54--- /dev/null+++ b/scripts/tests/test_agent_profile_docs.py@@ -0,0 +1,144 @@+#!/usr/bin/env python3+"""Bind profile help to existing authority, application and API boundaries.++Static source/document checks only. No agent, credential, listener, provider,+service, profile mutation or installed containment is exercised.+"""++import json+from pathlib import Path+import re+import shlex+import unittest+++ROOT = Path(__file__).resolve().parents[2]+NAMES = ("CENTRALIZED_MANAGEMENT.md", "UNIFIED_AGENT.md")+++def plain(text):+ return " ".join(text.replace("**", "").split())+++class AgentProfileDocsTest(unittest.TestCase):+ # Override these texts for actual-parent/adverse controls without editing+ # source files or manufacturing a mirror failure.+ texts = None++ def setUp(self):+ texts = self.texts or {name: (ROOT / "docs" / name).read_text() for name in NAMES}+ self.central = texts[NAMES[0]]+ self.guide = plain(self.central)+ self.agent = plain(texts[NAMES[1]].split(+ "## Remote Configuration (Agent Profiles, Pro/legacy Pro+/Cloud)", 1)[1].split(+ "\n## Uninstall", 1)[0])++ def test_shipped_mirrors_match(self):+ for name in NAMES:+ with self.subTest(name=name):+ self.assertEqual((ROOT / "docs" / name).read_bytes(),+ (ROOT / "frontend-modern/public/docs" / name).read_bytes())++ def test_supported_keys_match_the_existing_schema_and_startup_consumer(self):+ schema = (ROOT / "internal/models/profile_validation.go").read_text()+ keys = re.findall(r'Key:\s+"([^"]+)"', schema.split(+ "var ValidConfigKeys = []ConfigKeyDefinition{", 1)[1].split(+ "// ValidationError", 1)[0])+ table = self.central.split("## Supported Configuration Keys", 1)[1].split(+ "### Monitoring", 1)[0]+ rows = re.findall(r"^\| `([^`]+)` \|", table, re.MULTILINE)+ self.assertEqual(rows, keys)+ startup = (ROOT / "cmd/pulse-agent/main.go").read_text().split(+ "func applyRemoteSettings(", 1)[1]+ for key in keys:+ with self.subTest(key=key):+ self.assertIn(f'case "{key}":', startup)+ self.assertIn("JSON numbers are interpreted as seconds", self.guide)++ def test_host_metrics_do_not_grant_command_authority(self):+ row = next(line for line in self.central.splitlines() if line.startswith("| `enable_host`"))+ self.assertIn("metrics collection only; does not grant command execution", row)+ self.assertNotIn("metrics + command execution", self.central)+ for phrase in ("not a profile key", "installed local authority", "agent:exec",+ "permitted agent binding", "monitoring-only runtime rejects remote",+ "cannot promote that runtime", "Leave commands off for monitoring"):+ self.assertIn(phrase, self.guide)+ authority = (ROOT / "internal/hostagent/agent.go").read_text()+ self.assertIn("ResolveCommandAuthority(a.commandAuthorityProfile, commandsEnabled)", authority)+ self.assertIn("commandConfigAllowedForToken", (ROOT / "internal/api/agent_ingest.go").read_text())++ def test_live_refresh_is_not_a_blanket_restart_or_live_reload_claim(self):+ main = (ROOT / "cmd/pulse-agent/main.go").read_text()+ self.assertRegex(main, r"remoteConfigRefreshInterval\s*=\s*1 \* time.Minute")+ live = (ROOT / "internal/hostagent/agent.go").read_text().split(+ "func remoteConfigAppliedWithoutRestart(", 1)[1].split("\n}", 1)[0]+ self.assertIn('case "interval", "report_ip", "disable_ceph", availabilitySettingsKey:', live)+ for text in (self.guide, self.agent):+ self.assertIn("host module running", text)+ self.assertIn("about once a minute", text)+ for key in ("interval", "report_ip", "disable_ceph"):+ self.assertIn(f"`{key}`", text)+ self.assertIn("successful startup fetch", text)+ self.assertIn("not an all-module live reload", text)+ self.assertNotIn("Profile changes take effect on the next agent restart", text)+ self.assertIn("keeps its current settings if a refresh fails", self.guide)+ self.assertIn("do not disable signature or TLS verification", self.guide)++ def test_rollout_keeps_local_opt_outs_and_passive_acceptance(self):+ for phrase in ("hard opt-out", "cannot turn Docker/Podman collection back on",+ "shared profile change affects every agent", "Validate",+ "not host permissions", "non-production agent", "Read back both records",+ "normal config fetches and fresh reports", "not proof that every setting",+ "Do not restart, re-enrol or change a host identity",+ "Monitoring is interrupted during restart", "independent coverage"):+ self.assertIn(phrase, self.guide)+ startup = (ROOT / "cmd/pulse-agent/main.go").read_text()+ self.assertIn("b && cfg.DockerExplicitlyDisabled", startup)++ def test_removal_and_rollback_are_not_emergency_revocation(self):+ for phrase in ("does not undo settings already applied", "revoke its token",+ "revoke command authority", "Unassignment is not an emergency stop",+ "new version", "every affected agent", "local service procedure"):+ self.assertIn(phrase, self.guide)+ self.assertIn("does not undo settings already applied", self.agent)+ rollback = (ROOT / "internal/api/config_profiles.go").read_text().split(+ "func (h *ConfigProfileHandler) RollbackProfile(", 1)[1]+ self.assertIn("profiles[i].Version = p.Version + 1", rollback)+ self.assertIn("selected organisation's Pulse config storage", self.guide)++ def test_api_access_uses_real_ids_scope_and_desired_not_applied_state(self):+ for phrase in ("administrator access, `settings:write` token scope",+ "`agent_profiles` licence capability", "returned profile `id`",+ "not `prod-servers`", "server's desired configuration",+ "not an observation of what the process applied",+ "restricted by token binding", "never give an agent an administrator token",+ "before considering another write", "Do not blindly repeat POST"):+ self.assertIn(phrase, self.guide)+ routes = (ROOT / "internal/api/router_routes_registration.go").read_text()+ self.assertIn("RequireScope(config.ScopeSettingsWrite, RequireLicenseFeature", routes)+ handler = (ROOT / "internal/api/config_profiles.go").read_text()+ self.assertIn("input.ID = uuid.New().String()", handler)+ self.assertIn("if p.ID == input.ProfileID", handler)+ bodies = [json.loads(body) for body in re.findall(r"```json\n(.*?)```", self.central, re.DOTALL)]+ self.assertEqual(bodies[1]["profile_id"], "<returned-profile-uuid>")+ self.assertEqual(set(bodies[0]), {"name", "config"})++ def test_examples_keep_credentials_and_infrastructure_responses_private(self):+ commands = re.findall(r"```bash\n(.*?)```", self.central, re.DOTALL)+ self.assertEqual(len(commands), 1)+ for line in commands[0].splitlines():+ if line and not line.startswith("#"):+ words = shlex.split(line)+ self.assertEqual(words[:2], ["pulse_api", "GET"])+ self.assertTrue(words[2].startswith("/api/admin/profiles/"))+ self.assertNotIn("```http", self.central)+ for phrase in ("private header file", "same Bash session", "no redirects",+ "automatic retries", "Never paste a token or session cookie",+ "Copy as cURL", "not full responses", "manually redacted excerpt",+ "may call the configured AI provider", "not a read-only diagnostic",+ "not an empty profile list", "GET and POST only, not PUT or DELETE"):+ self.assertIn(phrase, self.guide)+++if __name__ == "__main__":+ unittest.main()diff --git a/scripts/tests/test_public_docs_workflow.py b/scripts/tests/test_public_docs_workflow.pyindex ffdc373f2e..5124ce8ee3 100644--- a/scripts/tests/test_public_docs_workflow.py+++ b/scripts/tests/test_public_docs_workflow.py@@ -25,6 +25,7 @@ SAFETY_STEP = "Exercise backup safety and diagnostic recipes"TESTS = ("test_production_rollout_docs.py","test_pmg_docs.py",+ "test_agent_profile_docs.py","test_pve_backup_troubleshooting_docs.py","test_vm_disk_diagnostics.py","test_memory_troubleshooting_docs.py",