KProx is a programmable BLE + USB keyboard, international keyboard, and mouse with an encrypted REST API, an on-device keepass credential store, an scripting engine, and a community gadget library.
KProx runs on the M5Stack AtomS3 Lite ESP32S3 and the M5Stack Cardputer Adv ESP32S3.
It presents itself to a paired host as a Bluetooth or USB keyboard and mouse, then accepts input from a web interface or REST API, letting you type into, click on, and control any HID-capable device without installing software on it.
Typical applications: unlocking unattended machines, mouse jiggling, canned text sequences, scripted UI testing, automated form entry on devices where you cannot install software.
This software is intended for personal use only, on systems and devices you own or have explicit authorization to operate. By using this project you accept full responsibility for how it is used.
The license granted by this project is automatically and irrevocably revoked for any use that is illegal, unethical, or unauthorized.
This project is a toy. The cryptographic implementations have not been audited or verified by security professionals. Do not use this software to store, transmit, or protect sensitive data in any production environment. USE AT YOUR OWN RISK.
| Document | Description |
|---|---|
| quick_start.md | Quick start guide — first steps, common tasks, at-a-glance reference |
| CARDPUTER_APPS.md | Complete Cardputer app list with descriptions and navigation reference |
| TOKEN_REFERENCE.md | Complete token string DSL reference: all tokens, syntax, examples |
| KEYPROX_SCRIPT_REFERENCE.md | KProx Script (.kps) language reference |
| API_REFERENCE.md | REST API endpoint reference |
KProx supports the following development devices out-of-the-box:
- PlatformIO
- Node.js (for build step)
Development workflow is tested in ubuntu. Development on other OSs will work but installation procedures for the prerequisits will change. Install the necessary dependencies in ubuntu with:
sudo apt-get update && sudo apt-get install -y platformio make nodejs npm bc
- Connect via USB-C and enter DFU mode:
- AtomS3: Hold side button 3-5 seconds until LED turns green.
- Cardputer ADV: Hold BtnG0, then press BtnRst.
- Run:
This minifies web assets, copies reference docs into
make build
data/, uploads the SPIFFS filesystem image, then flashes the firmware.
make ota
# or
make ota HOST=192.168.1.42OTA binary can also be uploaded via Settings -> OTA Firmware Update in the web interface.
KProx does not host its own access point. Factory defaults:
| Setting | Default |
|---|---|
| SSID | kprox |
| Password | 1337prox |
First-boot flow:
- Create a phone hotspot with the default credentials (2.4 GHz).
- Power on KProx. LED blinks orange while connecting, flashes green on success.
- Open
http://kprox.localor find the IP in your hotspot client list. - Go to WiFi Settings, enter your real network credentials, click Connect.
- Update the API Endpoint field in the sidebar to the new hostname or IP.
All API endpoints require authentication via HMAC-SHA256 over a single-use nonce (fetched from GET /api/nonce).
Request and response bodies are encrypted with AES-256-CTR + HMAC-SHA256 keyed from the API key.
Default API key: kprox1337 -- change this immediately via the web interface sidebar.
The credential store is an on-device KeePass KDBX 3.1 database stored in NVS or on the SD card. It can be opened by any compatible KeePass client (KeePassXC, KeePass 2, Strongbox, etc.).
Credentials support three fields: password (default), username, and notes. TOTP accounts are also stored inside the credential store, fully encrypted at rest.
The store must be unlocked before any credential or TOTP operation is possible. Unlock via the web interface or the CredStore app (see CARDPUTER_APPS.md).
Gate modes:
| Mode | Requirement |
|---|---|
| Key only | Symmetric passphrase (min 8 chars) |
| Key + TOTP | PIN then a live TOTP code |
| TOTP only | TOTP code alone; NTP sync required |
Storage location can be NVS (default) or SD card (/kprox.kdbx). Switching location while unlocked
migrates the database automatically.
Security options: auto-lock after inactivity, auto-wipe after N failed unlock attempts.
Register contents are stored in plaintext. Do not put secrets in registers, use the credential store.
| Action | Behavior |
|---|---|
| 1 click | Play active register |
| 2 clicks | Cycle to next register |
| Hold 5 s | Delete all registers |
See CARDPUTER_APPS.md for the complete app reference including per-app controls, icons, BtnG0 behaviour, and the navigation quick reference.
Quick summary — use arrow keys to navigate the launcher, ENTER to open an app, ESC or backtick to return. BtnG0 plays the active register from any app that does not override it. TAB shows each app's built-in help page.
| App | Description |
|---|---|
| KProx | Register playback and device status |
| FuzzyProx | Fuzzy-search all registers by name or content |
| RegEdit | Full-screen register editor |
| CredStore | Encrypted credential store — unlock before using {CREDSTORE} tokens |
| Gadgets | Install community token strings from GitHub |
| SinkProx | View and execute the unauthenticated sink buffer |
| Keyboard | Direct keyboard HID forwarding to the paired host |
| Clock | Current time, date, and timezone selector |
| QRProx | QR code for the web interface URL |
| SchedProx | Time-triggered register scheduling |
| TOTProx | TOTP 2FA authenticator — BtnG0 types the live code |
| Files | SD card file browser |
| KPScript | Run .kps scripts from the SD card |
| BootProx | Fire a register on boot with optional auto-disable |
| TimerProx | Countdown timer with deferred register playback |
| psCombatProx | ps-command combat mini-game over HID |
| MediaCtrl | Media transport controls (play, pause, stop, volume, mute) |
| Settings | All device configuration across 15 pages |
| Tab | Description |
|---|---|
| Registers | Create, edit, name, reorder, and play token string registers |
| Mouse | Trackpad for direct mouse control |
| Settings | WiFi, Bluetooth, USB, timing, device identity, app layout, CS security |
| Scheduled Tasks | Create and manage time-triggered token string tasks |
| Code Reference | Searchable token reference (loaded from device). See also |
| API Reference | Full REST API docs (loaded from device). See also API_REFERENCE.md. |
| Credential Store | Lock/unlock, add/delete/update credentials (password, username, notes), rekey, wipe, set |
| TOTProx | TOTP account management, live codes, gate configuration |
| Gadgets | Browse and install community gadgets from GitHub |
| Keymap Editor | Upload and manage custom keyboard layout JSON files |
| File Browser | SD card file manager: browse, create, edit, save, delete, run .kps scripts |
| BootProx | Configure and monitor the boot register: enable/disable, select register, set fire limit, reset count |
| KPScript Editor | Write, save, and run KProx Script files stored on the SD card |
| KPS Reference | KProx Script language reference (loaded from device). See also |
Recommended directory layout:
/
+-- scripts/ KProx Script files (.kps)
+-- config/ Configuration files read by scripts
+-- logs/ Log files written by scripts
+-- kprox.kdbx Credential store database (when CS location = SD)
Token strings can read, write, and execute files on the SD card. See TOKEN_REFERENCE.md for the
{SD_READ}, {SD_WRITE}, {SD_APPEND}, and {SD_EXEC} tokens.
KProx Script (.kps) is a line-oriented scripting language that runs directly on the device. Scripts are stored on the
SD card and can be executed from a token string ({SD_EXEC /scripts/hello.kps}), the KPScript app (see CARDPUTER_APPS.md), or the
KPScript Editor web tab.
For the full language reference see KEYPROX_SCRIPT_REFERENCE.md.
Quick example:
# auto_login.kps
set user {CREDSTORE username mysite}
set pass {CREDSTORE mysite}
set code {TOTP mysite}
if ${user} == ""
echo "Credential store locked{ENTER}"
return
endif
echo "${user}{TAB}${pass}{ENTER}"
sleep 2000
echo "${code}{ENTER}"
Gadgets are pre-built token string scripts in the gadgets/ directory. Install them from the Gadgets web
tab or the Gadgets app (see CARDPUTER_APPS.md).
{
"gadget": {
"name": "Random Mouse Walk",
"description": "Randomly moves the mouse around the screen forever.",
"content": "{LOOP}{MOVEMOUSE {RAND -100 100} {RAND -100 100}}{SLEEP {RAND 1000 3000}}{ENDLOOP}"
}
}To contribute a gadget: fork the repo, add a file to gadgets/ in the format above (keep name under 30 chars), test
it, and open a pull request.
Pipe token strings from a shell script:
echo "{SLEEP 1000}hello world{ENTER}" | bash tools/kpipe.shAll endpoints require X-Auth: hmac-sha256(apiKey, nonce). See API_REFERENCE.md for the full
reference.
src/
token_parser.cpp Token string DSL interpreter
kps_parser.cpp KProx Script interpreter
sd_utils.cpp SD card file utilities
credential_store.cpp KDBX 3.1 credential store (NVS or SD)
totp.cpp TOTP (accounts stored inside credential store)
registers.cpp Register storage and playback
api.cpp REST API
cardputer/ Cardputer apps and UI manager
web/ Web interface (minified into SPIFFS by build.js)
gadgets/ Community gadget scripts (JSON)
tools/ Shell utilities (kpipe, registers import/export, etc.)
TOKEN_REFERENCE.md Token string DSL reference
KEYPROX_SCRIPT_REFERENCE.md KProx Script language reference
API_REFERENCE.md REST API reference