Tools Reference
The built-in tools give the cloud agent real hands on your machine. Each tool runs in a sandbox with clear boundaries.
files
File operations confined to safe paths.
| Operation | Notes |
|---|---|
list |
Directory listing with sizes and mtimes |
read |
Read text files (size-capped) |
write |
Write text files (atomic) |
move / delete |
Rename / remove within allowed paths |
Safety: the tool refuses to touch paths outside the allowed roots (home, workspace, temp). Symlink escapes are rejected.
shell
A guarded, allowlisted command shell.
- Commands run through an allowlist of safe patterns (
ls,cat,df,uptime, …); anything matching a dangerous pattern (rm -rf /, fork bombs,sudowithout confirmation) is blocked before execution. - Output is streamed back line-buffered, so the dashboard log feels live.
- Each execution is logged and attached to the audit trail in the cloud.
Example the agent might run:
df -h / && du -sh ~/Downloads | sort -h | tail -5
net
Network helpers for connectivity checks and HTTP.
| Helper | Use |
|---|---|
http |
GET/POST JSON requests (outbound only) |
ping / reachable |
Host / port reachability |
dns |
DNS lookups |
wake |
(LAN) wake-on-LAN helper, where supported |
Used by the cloud agent for health checks, webhooks and diagnostics.
sysinfo
System metrics for the live device dashboard.
| Metric | Snapshot interval |
|---|---|
| CPU usage % | every 10 s |
| Load average (1/5/15) | every 10 s |
| Memory total / used / % | every 10 s |
| Disk usage % | every 10 s |
| Uptime | every 10 s |
| Hostname, platform, arch, CPU model, cores, version, IP | on connect |
The cloud keeps the latest snapshot plus a rolling 180-point history per device and renders sparklines for CPU and memory in the dashboard.
Adding your own tool
Tools live in apps/desktop/src/tools/ and are plain ES modules. Each tool
exposes a run(action, args) and registers itself in
src/tools/index.js. Keep the same rules: validate input, never execute
untrusted data, and always stream results.