System
Query local system diagnostics via shell commands for operational visibility.
Usage
# Create system diagnostics model
swamp model create @webframp/system sys-diag
# Get disk usage
swamp model method run sys-diag get_disk_usage
# Get memory info
swamp model method run sys-diag get_memory
# Get uptime and load averages
swamp model method run sys-diag get_uptime
# Get top processes by CPU
swamp model method run sys-diag get_processes
# Get network interfaces
swamp model method run sys-diag get_network_interfaces
# Get OS info
swamp model method run sys-diag get_os_infoMethods
- get_disk_usage - Filesystem usage from df
- get_memory - Memory and swap usage from free
- get_uptime - Boot time, uptime string, and load averages
- get_processes - Top 20 processes sorted by CPU usage
- get_network_interfaces - Network interfaces and addresses from ip
- get_os_info - OS release info and kernel version
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.08.28.1
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.26.2
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
Resources
2026.08.28.1
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.26.2
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.2
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.25.1
Changed: Updated labels for improved extension discoverability. Added cross-cutting category labels (security, observability, finops, infrastructure, networking, compliance, devops, ai, incident-response) where applicable.
updated labels
2026.08.24.5
Added: list_services method — enumerate systemd service units filtered by
active state (active/inactive/failed) and unit type (service/timer/socket/mount).
Added: list_ports method — list TCP ports in LISTEN state with their owning
process name and PID via ss -tlnp.
Added: search_processes method — filter running processes by command name
substring, minimum %CPU threshold, and/or minimum %MEM threshold. Returns
matching processes sorted by CPU usage.
Added: Three new resource specs: services, listening_ports, and
search_results to store output from the new methods.
Modified 1 models
2026.08.24.4
Added: Output metadata attributes for observability.
durationMs: Method execution duration in milliseconds.collectedBy: Extension name that produced the data.fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).
2026.08.24.3
Fixed: Added missing description field to the 2026.08.24.2 upgrade entry. The swamp binary's model loader requires description: string on every upgrade entry; the prior publish omitted it, causing a Zod validation error at load time.
2026.08.24.2
Added Troubleshooting section documenting command-not-found errors, get_os_info graceful degradation, ip -j requirement, Linux-only restriction, and zero-config design.
2026.08.21.2
Changed: Errors from shell commands now say what went wrong and which
command was involved. Previously, if a command binary couldn't be spawned at
all (not installed, not on PATH, not executable), the raw OS error
propagated with no indication of which command swamp was trying to run; now
the error names the full command line alongside the OS error. A non-zero
exit now reports the exit code in addition to stderr. get_network_interfaces
now reports which command produced unparseable output if ip -j addr show
returns something that isn't valid JSON, instead of a bare SyntaxError.
get_os_info now logs a reason when /etc/os-release can't be read, instead
of silently continuing with an empty osRelease and no record of why.
2026.08.21.1
Changed: Tightened get_processes's count argument to require a
positive integer. The method already used it as a slice length starting
from the top of the sorted process list, so a zero, negative, or fractional
value never produced anything meaningful — this catches that at validation
time instead of silently returning zero or misshapen results.
2026.07.18.1
Added: An upgrades array entry (no-op) to diagnostics.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.
2026.08.21.1
Changed: Tightened get_processes's count argument to require a
positive integer. The method already used it as a slice length starting
from the top of the sorted process list, so a zero, negative, or fractional
value never produced anything meaningful — this catches that at validation
time instead of silently returning zero or misshapen results.
2026.07.18.1
Added: An upgrades array entry (no-op) to diagnostics.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.
2026.07.18.1
Added: An upgrades array entry (no-op) to diagnostics.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.
updated platforms
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned