The bound device runs a small lifeline core plus a signed plugin. The most basic agent must always accept and execute confirmed shell commands natively — shell is not break-glass and not plugin-optional. Other ops still come from the signed plugin. This page maps that surface against the control plane.
GET /api/admin/devices/:id
→ device.status.agent.commands. After the shell-capable core
is installed, that list includes shell. Until upgrade,
live lab may still report without shell.
Earlier modular builds treated shell as local break-glass only. That was the
wrong product direction: the most basic device agent must run shell
(with server confirmation). MQTT and collect_status already worked;
shell was missing from the advertised core surface.
Compare these stories when something fails:
COMMAND_TYPES)Think of three replaceable pieces on A/B devices. Only core + plugin advertise remote commands.
Reach the assigned edge at all costs, durable ledger/outbox,
recovery, signed updates, minimal status, and shell.
Native:
collect_status, agent_upgrade, reboot,
shell (confirmed)
Independent rollback deadlines for connectivity and updates. Not a command agent — no remote command types.
Out-of-process ops (set_*, network tests, WG/IPsec, scans). Signed manifest is the allowlist. Shell stays on the core so the basic agent works even with zero plugins.
Deployments may set CLOUDCONTROL_DISABLE_SHELL=1 on the
device to turn shell off. Default is on.
Captured 2026-07-19 against the live lab unit via admin API only.
| Online | live · MQTT via edge-nyc3-01 |
|---|---|
| Agent | cloudcontrold · 0.3.2-lifeline · profile full · protocol 3 |
| Core SHA-256 | d211e2646e5fef36f32667d31c75aad074c40023899e3dd1e6bc2ed8b1f6ce87 |
| Core size | 2,000,748 bytes (UPX) |
| Plugin | cloudcontrol-legacy · same version |
| Shell (pre-upgrade lab) | Was not advertised on 0.3.2-lifeline without native shell; code now treats shell as core native — rebuild/upgrade to pick up |
| Proven path | collect_status succeeded (delivered → acked → completed ≈ 553 ms) |
agent_upgrade, block_client, bt_scan, cell_scan, collect_clients, collect_status, firmware_check, ipsec_join, ipsec_leave, network_iperf, network_path_test, network_port_test, network_speedtest, reboot, set_firewall, set_lan, set_system, set_wifi, wireguard_onboard, wireguard_remove
Compare each command type across the modular core, the legacy plugin, the server type allowlist, and the live lab advertisement. Rows highlighted in warm tint are mismatches (server still names the type; modular device does not advertise it).
| Command type | Core | Plugin | Server | Live | Notes |
|---|
These sources still describe an older or broader surface than modular lifeline ships.
POST /api/admin/devices/:id/commands with type in server COMMAND_TYPES.agent.commands or agent.capabilities, the type must appear in their union (case-insensitive).409 device_capability_not_advertised.agent-command-policy.js) are separate from advertise/deny.uname -a| Path | Result |
|---|---|
| Lab unit on pre-shell core | device_capability_not_advertised — expected until upgrade |
| After shell-capable core upgrade | Admin enqueue shell with payload.command: "uname -a" (confirmed) → stdout |
collect_status inventory (always) |
Kernel / hostname / arch without full uname string |
GET /api/admin/devices/:idstatus.agent.commands, .capabilities, .plugins[]public/downloads/cloudcontrol-plugin-legacy-*.plugin.jsonCOMMAND_TYPES in src/routes/admin.jsCOMMANDS array in this HTML (and the snapshot pills) when the surface changes
Machine-oriented twin (markdown): docs/agent-command-surface.md in the repo.
Prefer this HTML page for operators.