Skill: ivangdavila/beszel (version 1.0.0)

--- name: Beszel slug: beszel version: 1.0.0 homepage: https://clawic.com/skills/beszel description: Deploy, secure, and troubleshoot Beszel monitoring with Docker agents, alert tuning, and upgrade-safe operations for self-hosted servers changelog: Initial release with Beszel deployment guidance, alert tuning workflow, and incident troubleshooting playbooks. metadata: {"clawdbot":{"emoji":"📊","requires":{"bins":["docker"]},"os":["linux","darwin","win32"],"configPaths":["~/beszel/"]}} --- ## Setup On first use, explain planned local storage in `~/beszel/` and ask for confirmation before creating or updating files. ## When to Use User needs help planning, deploying, or maintaining Beszel for infrastructure monitoring. Agent handles topology choices, secure agent onboarding, alert calibration, and upgrade-safe operations. ## Architecture Memory lives in `~/beszel/`. See `memory-template.md` for setup. ```text ~/beszel/ ├── memory.md # Current environment, goals, and priorities ├── nodes.md # Agent inventory and ownership ├── alerts.md # Alert thresholds and escalation targets └── incidents.md # Incident timeline and recovery notes ``` ## Quick Reference | Topic | File | |-------|------| | Setup behavior | `setup.md` | | Memory structure | `memory-template.md` | | Deployment topologies | `deployment-patterns.md` | | Alert calibration workflow | `alert-tuning.md` | | Diagnostics and recovery | `diagnostics-playbook.md` | ## Data Storage All skill files are stored in `~/beszel/`. Before writing new files, summarize the planned changes and get user confirmation. ## Core Rules ### 1. Define Monitoring Scope Before Installation - Confirm which hosts, services, and failure modes matter most before recommending a layout. - Prioritize high-impact systems first so coverage is meaningful from day one. ### 2. Keep Agent Access Minimal - Use least privilege for monitored hosts and avoid broad root-level automation by default. - Treat onboarding credentials as sensitive and avoid copying secrets into workspace notes. ### 3. Baseline First, Then Tune Alerts - Collect a short baseline period before applying strict thresholds. - Tune alert levels with operating context such as business hours, maintenance windows, and expected burst patterns. ### 4. Troubleshoot with a Fixed Sequence - Validate service status, agent connectivity, clock sync, and resource pressure in a consistent order. - Isolate one variable at a time to avoid changing many factors during an active incident. ### 5. Make Upgrades Reversible - Require backup and rollback steps before version changes. - Upgrade one environment at a time and confirm health before broader rollout. ### 6. Keep Operations Memory Current - Record node ownership, alert intent, and previous incidents after meaningful changes. - Convert repeated incidents into prevention rules and adjust thresholds accordingly. ## Common Traps - Enrolling many agents before defining alert ownership -> noisy incidents with unclear responders. - Copying thresholds from another environment -> chronic false positives or missed real failures. - Upgrading hub and agents simultaneously -> hard-to-debug version mismatch issues. - Ignoring host clock drift -> misleading timelines and confusing incident analysis. - Logging sensitive credentials in notes -> unnecessary security exposure. ## Security & Privacy **Data that may leave your machine (only when user configures external integrations):** - Monitoring notifications sent to selected channels or alerting tools. - Metadata required by external notification endpoints chosen by the user. **Data that stays local by default:** - Monitoring topology, node notes, threshold history, and incident logs in `~/beszel/`. **This skill does NOT:** - Enable external alert destinations automatically. - Create new credentials without explicit user approval. - Send undeclared network requests. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `monitoring` — monitoring architecture and operational standards - `server` — server diagnostics and maintenance workflows - `self-host` — self-hosted deployment and hardening practices - `docker` — container runtime and image management discipline - `docker-compose` — multi-service orchestration patterns ## Feedback - If useful: `clawhub star beszel` - Stay updated: `clawhub sync`

path: alert-tuning.md
content: # Beszel Alert Tuning Workflow

## Objective

Tune alerts so incidents are surfaced early without creating constant noise.

## Step 1: Capture Baseline

- Observe normal behavior for a short period before aggressive tuning.
- Separate expected peaks from true abnormal states.
- Document known maintenance windows and batch workloads.

## Step 2: Define Severity Tiers

- `warning`: unusual but not urgent conditions.
- `critical`: response required now to avoid impact.
- `urgent`: active service disruption or severe risk.

Apply clear response expectations for each tier.

## Step 3: Start Conservative

- Begin with broader thresholds to reduce false positives.
- Tighten gradually only after reviewing recent incidents.
- Keep one change per cycle so results are attributable.

## Step 4: Route Alerts by Ownership

- Every alert class must have a first responder.
- Define escalation targets for unresolved critical alerts.
- Avoid shared ownership with no clear accountable person.

## Step 5: Review Weekly

- Count false positives by alert type.
- Capture missed incidents and why detection lagged.
- Update thresholds, suppression windows, or service grouping.

## Common Recovery Actions

- Alert storm after deployment -> widen threshold temporarily, inspect release impact, and restore tighter limits once stable.
- Repeated disk pressure alerts -> track growth trend and add capacity planning note.
- CPU spikes at predictable times -> document workload schedule and tune threshold window.
- Frequent node disconnect alerts -> investigate network stability and clock sync before changing alert logic.


path: deployment-patterns.md
content: # Beszel Deployment Patterns

## Goal

Choose a topology that gives reliable monitoring signals while keeping management overhead predictable.

## Pattern A: Single Host Baseline

Use when:
- One primary server hosts most critical workloads.
- User wants fastest path to first useful alerts.

Guidelines:
- Start with one hub and one agent in the same environment.
- Validate CPU, memory, disk, and uptime reporting before adding more nodes.
- Define ownership for each alert stream immediately.

## Pattern B: Hub Plus Remote Agents

Use when:
- Multiple servers or sites must be monitored.
- Operations are distributed across teams or networks.

Guidelines:
- Add agents incrementally and verify each one before onboarding the next.
- Keep network exposure narrow and review node-level permissions.
- Tag nodes by environment to separate production and non-production noise.

## Pattern C: Staged Expansion

Use when:
- Current setup is unstable or alert fatigue already exists.
- Team needs confidence before broad rollout.

Guidelines:
- Start with the highest-risk systems first.
- Capture one week of baseline behavior before tightening thresholds.
- Require rollback notes for every topology change.

## Decision Checklist

- Which incidents are most expensive if detected late?
- Which nodes need immediate coverage vs later onboarding?
- Who owns first response and escalation?
- What rollback path exists for each deployment change?


path: diagnostics-playbook.md
content: # Beszel Diagnostics Playbook

## Objective

Resolve monitoring failures quickly with a consistent triage sequence.

## Triage Order

1. Confirm symptom scope:
- Is the issue one node, one service group, or the full stack?

2. Check component health:
- Validate hub and agent process status.
- Check recent restart loops or crash indicators.

3. Verify connectivity:
- Confirm network path between hub and agent.
- Check DNS resolution and firewall policies.

4. Validate time consistency:
- Compare host clocks for hub and agents.
- Correct drift before interpreting event timelines.

5. Inspect resource pressure:
- Review CPU, memory, disk, and I/O pressure on impacted nodes.
- Correlate telemetry gaps with host saturation windows.

6. Confirm version compatibility:
- Check hub and agent versions before concluding protocol issues.

## Incident Note Template

Use this minimal format in `incidents.md`:

```markdown
## YYYY-MM-DD - Incident Title
- Impact:
- Detection signal:
- Root cause:
- Fix applied:
- Prevention update:
```

## Escalation Guidance

- Escalate immediately when monitoring blind spots affect production.
- Escalate when repeated disconnects persist after connectivity checks.
- Escalate if upgrades introduce persistent metric gaps.

## Post-Incident Follow-up

- Update alert thresholds only after root cause is confirmed.
- Add one preventive rule tied to the incident.
- Record owner and due date for unresolved remediation.


path: memory-template.md
content: # Memory Template - Beszel

Create `~/beszel/memory.md` with this structure:

```markdown
# Beszel Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending

## Context
- Monitoring scope and critical services
- Reliability goals and risk tolerance
- Constraints for maintenance and response

## Node Inventory
- Node name -> role -> owner -> criticality
- Connectivity notes and known constraints

## Alert Strategy
- Primary thresholds by service class
- Escalation path and response expectation
- Known noisy alerts and suppression approach

## Incident Notes
- Timeline summary for major incidents
- Root cause and validated fix
- Prevention actions to apply next time

## Notes
- Observed preferences inferred from behavior
- Important pending follow-ups

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Context still evolving | Keep learning during normal operations |
| `complete` | Monitoring model is stable | Operate with current assumptions |
| `paused` | User wants less setup detail | Minimize follow-up questions |
| `never_ask` | User asked to stop discovery | Use only explicit instructions |

## Rules

- Use concise natural-language notes, not exposed config keys.
- Update `last` whenever monitoring context changes.
- Promote repeated incidents into prevention rules.
- Never delete prior context without confirmation.


path: setup.md
content: # Setup - Beszel

If `~/beszel/` does not exist or is empty, start with transparent onboarding. Explain which local files are useful, why they help, and ask for confirmation before writing anything.

## Your Attitude

Be practical, calm, and reliability-focused. Keep conversations direct and actionable so the user can improve monitoring coverage without extra complexity.

## Priority Order

### 1. First: Integration

In the first exchanges, clarify when this should activate in future conversations.

Ask naturally:
- Should this activate whenever they mention Beszel, monitoring alerts, node health, or agent failures?
- Should it proactively flag risky thresholds and missing coverage, or only respond when asked?
- Are there contexts where it should stay passive?

### 2. Then: Understand Environment and Risk

Build a fast baseline:
- Which hosts and services are currently monitored
- Which incidents are most costly for them
- Existing on-call or escalation workflow

Use open questions and adapt to the level of detail the user wants.

### 3. Finally: Capture Operational Detail

If they want deeper support, collect:
- Alert routing and expected response times
- Maintenance windows and upgrade cadence
- Known blind spots and recurring false positives

If they want speed, keep lightweight defaults and move directly to immediate fixes.

## What You Are Saving Internally

Track only reusable context:
- Activation preferences for future sessions
- Node inventory, ownership, and critical services
- Alert strategy and escalation targets
- Incident patterns and proven fixes

After updates, summarize what was saved in plain language so the user can correct or remove anything quickly.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)