Shellwire

shellwire runs as a WebSocket server, providing a bridge that lets remote clients execute shell commands with full system access. While fully compatible with Linux and macOS, it is uniquely engineered for Android devices. Android applications typically lack proper terminal access, making it difficult to run local AI agents or advanced tools on-device. Shellwire solves this by running inside Termux and exposing a WebSocket server, acting as a bridge to give Android apps a complete, desktop-grade shell environment.

Architecture & Security

• Stable token auth — Token is generated once and persists across daemon restarts.
• Single client — Supports one active connection at a time, with robust reconnection handling.
• Health endpoint — HTTP GET /health exposed on the same port for monitoring.

Session Management

• Concurrent execution — Dispatch and process up to 4 simultaneous background commands.
• Interactive PTY sessions (POSIX) — Full pseudo-terminal support, including dynamic terminal resizing.
• Environment Tracking — Persists working directory (CWD) and exported environment variables across distinct commands.

Process Isolation & Mobile Optimizations

• Termux / Android Optimized — Built-in resilience against mobile network handoffs, terminal DOZE states, and Android phantom process killers. Ensures extreme stability for long-running mobile environments.
• Robust Process Isolation — Prevents zombie processes via process-group escalation kills (SIGTERM → SIGKILL) and forcefully protects against runaway output streams.
• Compound Command Rewriting — Automatically rewrites shell background chains (e.g., A && B & -> A && { B & }) to ensure standard execution behavior.

Installation

# Via pip
pip install shellwire

Or install from source:

git clone https://github.com/shantoislamdev/shellwire.git
cd shellwire
pip install -e ".[dev]"

Quick Start

# Start the daemon (foreground)
shellwire start

On first start, a stable auth token is generated and displayed. Save it — you’ll need it to connect your client. Please read the documentation to learn how to create your client and connect with Shellwire.