Skip to content

About

Run SSH commands from your Flipper Zero over wired Ethernet or WiFi, through an ESP32-S3 add-on board

Topics

esp32esp32-s3ethernetflipper-zeroflipper-zero-appflipperzerosshssh-clientw5500wifi

Resources

Readme
GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

SSH Runner for Flipper Zero

Run SSH commands from your Flipper Zero over wired Ethernet or WiFi, through an ESP32-S3 add-on board.

License: GPL-3.0 Latest release Flipper firmware: Unleashed | Official ESP32-S3

The core flow on the Flipper's screen in four steps: the Home menu with Quick Connect selected, Quick Connect with user@192.168.1.10 typed, the new host key's SHA256 fingerprint with Cancel and Trust, and the output of uname -a ending in Exit 0
Shown in demo mode with example data.

SSH Runner pairs a Flipper Zero app with firmware for an ESP32-S3 board that has a W5500 Ethernet port. The board handles networking and cryptography (libssh); the Flipper is the keyboard and screen. Pick a host, authenticate, run a command or a script, and read the output.

Contents: Features · Screenshots · Hardware · Installation · Usage · Documentation · Building From Source · Security · Roadmap · Contributing · License · Acknowledgments

Features

  • Wired or wireless: LAN (W5500 Ethernet) and 2.4 GHz WiFi, DHCP or static, with automatic fallback between them.
  • Password or key authentication: Ed25519, ECDSA and RSA keys from the SD card, or keys generated by the app; an encrypted key needs its passphrase only once.
  • Host-key pinning per host: prompt, strict or off.
  • Commands your way: one-liners, saved commands per host or global, and shell scripts from the SD card.
  • Readable output with the exit code and run time; very long output keeps its beginning and end.
  • Ready to try: built-in example commands and a system-info script.
  • PC companion: sshrunner edits hosts, commands, keys and scripts over USB, with backups before every change.
  • Optional secret protection: encrypt the board's stored credentials with an eFuse key.

Screenshots

Animation of a session on the real board: Home with the board's address, the saved host homelab and its page, a key login straight to the run menu, the output of fetch, usage with CPU, memory and disk bars, and services, then the SD card script health.sh with its checks, 5/5 passed and exit code 0

Every screen below is from the app's demo mode (simulated board, example data), at 4× the Flipper's 128×64 screen.

Hosts list with the host nas and Add Host
Hosts: saved hosts by name		 Host page: Connect, alias, user and host
Host page: user, address, auth, commands		 Recent list with pi@192.168.4.1 and nas: user@192.168.1.10
Recent: the last connections
Run Script? confirmation: backup.sh, 170 B, runs with bash, Cancel or Run
Scripts: name, size and shell shown first		 Host Key Changed warning for pi@192.168.4.1 with Cancel and Options
Host key changed: a warning, never a silent connect		 Choose Network: WiFi networks with lock icons and signal bars
WiFi: scan and join from the Flipper
LAN page with Mode set to Static, static IP and netmask
LAN: DHCP or a static address		 Ping result for 8.8.8.8: LAN and WiFi, 4 of 4 each, average 2 ms
Ping: through LAN and WiFi		 Keys list with Generate Key and id_ed25519 (default)
Keys: generate or import
Key card for id_ed25519: Ed25519, default key, encrypted, SHA256 fingerprint
Key details: type, passphrase, fingerprint		 Settings menu with Developer, Security and Restore Examples
Settings: restore the built-in examples; Developer appears only with the Flipper's Settings > System > Debug on		 Protect Secrets? warning: cannot be undone, burns a key into the ESP32, updates still work
Security: optional secret protection

sshrunner's editor in a terminal: tabs for Hosts, Commands, Keys, Scripts and Backups; the Hosts tab lists nas, pi and v6 with target, auth, transport, host-key policy and command count; key hints at the bottom
The PC tool: sshrunner edits hosts, commands, keys and scripts from a computer (PC Tool)

Hardware

Part Notes
Flipper Zero Unleashed unlshd-094 or official 1.5.1 firmware, with an SD card
SSH Runner add-on board ESP32-S3-WROOM-1 (16 MB flash, 8 MB PSRAM), W5500 Ethernet with RJ45, USB-C; plugs straight onto the Flipper's GPIO header, no wiring
or Waveshare ESP32-S3-ETH ESP32-S3R8, 16 MB flash, W5500 Ethernet with RJ45, USB-C; with 3–4 jumper wires, see the wiring below
Ethernet cable or a 2.4 GHz WiFi network the ESP32-S3 has no 5 GHz radio

Wiring (Waveshare ESP32-S3-ETH)

Flipper Zero GPIO ESP32-S3-ETH Use
13 (TX) GPIO18 (header H1 pin 10) always
14 (RX) GPIO17 (header H1 pin 7) always
8, 11 or 18 (GND) GND always
9 (3V3) 3V3 header pin portable use
  • Desk use: three wires; the board is powered from its own USB-C.
  • Portable use: add a wire from the Flipper's GPIO header pin 9 (3V3) to the board's 3V3 pin; the board then runs from the Flipper's battery, with no USB-C cable.

Warning

Never plug in the board's USB-C while the 3V3 wire is connected: that ties two power supplies together. Remove the 3V3 wire before connecting USB-C (for example to flash the firmware). Leave "5V on GPIO" off on the Flipper.

Pin details: Hardware and Wiring.

The SSH Runner add-on board (rev 0.1) is built and tested. Its design files are in hardware/ (CC BY-NC-SA 4.0: source-available, non-commercial), to order or build yourself; on rev 0.1 the status LED is a hand-fitted part (erratum E1). Its USB-C may stay plugged in while it sits on the Flipper.

3D render of the SSH Runner rev 0.1 board from above at an angle: the ESP32-S3 module, the W5500 chip, a USB-C port, an RJ45 jack and two rows of right-angle header pins on black solder mask 3D render of the SSH Runner rev 0.1 board from below: the SSH Runner name, rev 0.1, the project's GitHub address and a logo in white on black, with the header pins along the bottom edge

SSH Runner rev 0.1, the custom add-on PCB: design files, how to order, and errata.

Installation

Download the files from the latest release.

Flipper App

The easiest way is the Flipper Apps Catalog: connect the Flipper over USB, open that page in desktop Chrome or Edge and click Install, or find SSH Runner under Apps in the Flipper mobile app. Then open it from Apps > GPIO > SSH Runner.

To install it by hand, download the official build, ssh_runner-official.fap: it runs on the official and on the Unleashed firmware. Copy it to SD Card/apps/GPIO/ with qFlipper or a card reader. ssh_runner-unleashed.fap is optional, for Unleashed only (it scrolls long values in lists instead of showing their end).

If the Flipper reports an API mismatch or an outdated app after a firmware update, update the app from the catalog or download the latest release. A Flipper app runs when its API major version equals the firmware's and its minor version is not newer. The official build targets API 88.2, which the official firmware 1.5.1 (88.2) and Unleashed unlshd-094 (88.19) both accept.

ESP32 Firmware

Download the zip for your board, flipper-ssh-runner-esp32-waveshare-v<version>.zip (Waveshare ESP32-S3-ETH) or flipper-ssh-runner-esp32-addon-v<version>.zip (SSH Runner add-on, rev 0.1 and later), unzip it and connect the board's USB-C (3V3 wire removed). On a first install, erase the flash and write the factory image (-factory.bin) at 0x0; on an update, write only the app image (-app.bin) at 0x20000, without erasing, which keeps the board's saved WiFi network and trusted host keys. The simplest way is in the browser, with Spacehuhn's ESPTool in desktop Chrome or Edge, step by step in the Quick Start. Or with esptool (<board> is waveshare or addon):

# first install
esptool.py --chip esp32s3 -p <port> erase_flash
esptool.py --chip esp32s3 -p <port> write_flash 0x0 flipper-ssh-runner-<board>-v<version>-factory.bin
# update
esptool.py --chip esp32s3 -p <port> write_flash 0x20000 flipper-ssh-runner-<board>-v<version>-app.bin

The firmware burns no eFuses unless you enable secret protection in the app.

PC Tool (optional)

Archives for Linux, macOS and Windows (sshrunner_<version>_<os>_<arch>), plus .deb and .rpm packages. See cli/README.md.

Usage

  1. Put the add-on board on the Flipper, or wire the Waveshare board to it and power it (USB-C, or the 3V3 wire).
  2. Open SSH Runner. The header shows the board's address once it has a network.
  3. Network > LAN: plug in an Ethernet cable, or Network > Join WiFi to pick a network.
  4. Quick Connect: type user@host, check the host key, enter the password.
  5. Pick a command, or type one, and read the output. Save the host to reuse it.

Step by step, with what each message means: docs/QUICKSTART.md.

Documentation

Document What it covers
Quick Start Wiring, flashing, installing, the first connection, messages
Hardware and Wiring Pin assignments, desk and portable power
PC Tool (sshrunner) Editing the Flipper's hosts, commands, keys and scripts from a computer
Flipper App Screens, SD card files, examples, demo mode, compatibility
Architecture Repository layout and build outputs
UART Protocol The link between the Flipper and the board
Security Stored secrets, secret protection, host keys, wiping
Changelog Changes in each release
Contributing Issues, pull requests, running the checks
Third-Party Components Components and their licenses

All documents, grouped: docs/README.md.

Building From Source

Requirements: Docker (the ESP-IDF, uFBT and Go toolchains run in pinned containers or a local Python venv; nothing is installed globally) and Python 3.

# Linux / WSL
tools/check.sh
# Windows (PowerShell)
python -m venv venv
venv\Scripts\pip install --cache-dir .cache\pip -r requirements.txt
powershell -ExecutionPolicy Bypass -File tools\check.ps1

This builds the Flipper app for both firmwares, the ESP32 firmware and the PC tool, and runs the tests. Repository layout: docs/ARCHITECTURE.md; UART protocol: docs/PROTOCOL.md.

Security

The board stores WiFi credentials, remembered passwords and trusted host keys in its flash, unencrypted by default. Settings > Security > Protect Secrets encrypts them with a key burned into an eFuse; this cannot be undone. Private keys stay on the Flipper's SD card. Erase the board (esptool.py --chip esp32s3 -p <port> erase_flash) before giving it away. Threat model, details and how to report a vulnerability: docs/SECURITY.md.

Roadmap

  • Custom add-on PCB for the Flipper's GPIO header
  • Several saved WiFi networks, joining whichever is in range

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for how to report a bug, run the checks and send a change.

License

The firmware, the Flipper app, the PC tool and the scripts in hardware/tools/ are GPL-3.0-only.

The hardware design in hardware/ is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) (hardware/LICENSE). Commercial use of the hardware design or any derivative works is not permitted without explicit permission from the author. For commercial licensing, contact: scx@gapp.nthu.edu.tw

Third-party components and their licenses: THIRD_PARTY.md.

Acknowledgments

About

Run SSH commands from your Flipper Zero over wired Ethernet or WiFi, through an ESP32-S3 add-on board

Topics

esp32esp32-s3ethernetflipper-zeroflipper-zero-appflipperzerosshssh-clientw5500wifi

Resources

Readme
GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Sponsor this project

Packages

Used by

Contributors

Languages