MeshExec CLI is a decentralized command execution system that enables multiple Bluetooth-enabled devices to form a self-healing mesh network for broadcasting, relaying, and executing shell commands securely without requiring Wi-Fi or central infrastructure. The system provides both CLI and TUI interfaces for managing command execution across distributed devices with role-based targeting and secure message passing.
User Story: As a system administrator, I want to execute shell commands across multiple devices in a mesh network, so that I can manage distributed systems without requiring centralized infrastructure.
- WHEN a user executes
meshexec run --target="all" "uptime"THEN the system SHALL broadcast the command to all connected devices in the mesh - WHEN a device receives a command packet THEN the system SHALL execute the command using the system shell and return results
- WHEN command execution completes THEN the system SHALL return stdout, stderr, exit code, and execution status to the originating device
- IF a command fails to execute THEN the system SHALL return error details and non-zero exit code
User Story: As a network operator, I want devices to automatically discover and connect to nearby mesh nodes via Bluetooth LE, so that the network can self-organize without manual configuration.
- WHEN a device runs
meshexec joinTHEN the system SHALL start advertising its presence via Bluetooth LE GATT services - WHEN a device is in join mode THEN the system SHALL scan for and connect to other advertising mesh nodes
- WHEN two devices establish connection THEN the system SHALL maintain the connection for message relay
- IF a connection is lost THEN the system SHALL attempt to reconnect and find alternative routes through the mesh
User Story: As a security-conscious administrator, I want all commands to be cryptographically signed and optionally encrypted, so that only authorized users can execute commands and sensitive data is protected.
- WHEN a command is sent THEN the system SHALL sign the message using ed25519 private key
- WHEN a device receives a command THEN the system SHALL verify the signature before execution
- IF signature verification fails THEN the system SHALL reject the command and log the security violation
- WHEN encryption is enabled THEN the system SHALL encrypt command payloads using AES-GCM with pre-shared keys
User Story: As a field technician, I want to target specific devices based on their roles, architecture, or operating system, so that I can execute relevant commands only on appropriate devices.
- WHEN a user specifies
--target="os=linux && role=worker"THEN the system SHALL only execute commands on devices matching both criteria - WHEN a user specifies
--target="!arch=arm"THEN the system SHALL exclude ARM architecture devices from execution - WHEN a device receives a targeted command THEN the system SHALL evaluate target expressions against local device attributes
- IF target criteria don't match THEN the system SHALL ignore the command but continue relaying it to other nodes
User Story: As a network administrator, I want to prevent message flooding and loops in the mesh network, so that network performance remains optimal and commands don't execute multiple times.
- WHEN a message is created THEN the system SHALL assign a TTL (time-to-live) value starting at 5
- WHEN a device relays a message THEN the system SHALL decrement the TTL by 1
- IF TTL reaches 0 THEN the system SHALL drop the message and not relay it further
- WHEN a device receives a duplicate message THEN the system SHALL ignore it based on message ID tracking
User Story: As a system operator, I want to view real-time status of connected devices and command execution results, so that I can monitor the health and activity of the mesh network.
- WHEN a user runs
meshexec listTHEN the system SHALL display all currently connected peer devices - WHEN a user runs
meshexec statusTHEN the system SHALL show execution status of recent commands - WHEN a user runs
meshexec tuiTHEN the system SHALL launch a terminal UI dashboard showing live network status - WHEN command results are received THEN the system SHALL aggregate and display them in the appropriate interface
User Story: As a safety-conscious administrator, I want to preview commands before execution and filter dangerous operations, so that I can prevent accidental system damage.
- WHEN a user specifies
--dry-runflag THEN the system SHALL show what would be executed without actually running commands - WHEN safe mode is enabled THEN the system SHALL reject potentially dangerous commands like
rm -rf - WHEN a device has an allow/deny list configured THEN the system SHALL only execute commands from authorized sources
- IF a command is rejected by safety filters THEN the system SHALL log the rejection reason and notify the sender
User Story: As a system administrator, I want to configure device settings like roles, allow/deny lists, and security options through configuration files, so that I can easily manage device behavior without command-line arguments.
- WHEN the system starts THEN it SHALL read configuration from INI or TOML files in standard locations
- WHEN a configuration file contains device role settings THEN the system SHALL apply those roles for targeting
- WHEN allow/deny lists are specified in config THEN the system SHALL enforce command filtering based on those rules
- IF configuration file is malformed THEN the system SHALL log errors and fall back to default settings
User Story: As a developer, I want the system to provide reliable message delivery across the mesh network, so that commands reach their intended targets even if direct connections fail.
- WHEN a direct connection to target device is unavailable THEN the system SHALL route messages through intermediate mesh nodes
- WHEN a mesh node receives a message not intended for it THEN the system SHALL relay the message to connected peers
- WHEN network topology changes THEN the system SHALL automatically discover new routing paths
- IF message delivery fails after all retry attempts THEN the system SHALL report delivery failure to the originating user