Skip to main content
Version: 0.4.x

VibeKeys Max Remote Control Mode

In remote control mode, VibeKeys Max connects to your computer through an MQTT broker and lets you drive Claude Code or OpenAI Codex with voice input and physical controls — from wherever you happen to be. No port on your PC needs to be exposed: both ends are just MQTT clients of the same broker.

Both sides must be on 0.4.x

The MQTT protocol is new in 0.4.0 and incompatible with earlier versions. Your device needs firmware v0.4.0+ and your computer needs vibetty 0.4.x — older firmware will not connect or display correctly. If your device is still on 0.3.x, switch to the 0.3.x docs with the version dropdown at the top of this page.

What You'll Need​

Prerequisites
  • VibeKeys Max with firmware v0.4.0 or newer
  • A computer running macOS, Linux, or Windows 10 (1809+) / Windows 11 with vibetty 0.4.x
  • Claude Code 2.1.0 or newer, or OpenAI Codex
  • An MQTT broker — either vibetty's built-in broker (zero setup) or any hosted MQTT service

Step 1: Start the coding agent server with vibetty​

vibetty is the bridge between VibeKeys Max and your coding agent (Claude Code or OpenAI Codex). It runs the agent in a terminal on your computer and shares the session over MQTT.

Download the vibetty binary​

Grab the latest pre-built binary from the vibetty releases page. Pick the build for your platform, or use the commands below.

macOS with M chip​

curl -LO https://github.com/second-state/vibetty/releases/latest/download/vibetty-macos-arm64
chmod +x vibetty-macos-arm64
sudo mv vibetty-macos-arm64 /usr/local/bin/vibetty

Windows​

Invoke-WebRequest -Uri "https://github.com/second-state/vibetty/releases/latest/download/vibetty-windows-x64.exe" -OutFile "vibetty.exe"
# Add to PATH or move to a directory in PATH

Linux​

wget https://github.com/second-state/vibetty/releases/latest/download/vibetty-linux-x64
chmod +x vibetty-linux-x64
sudo mv vibetty-linux-x64 /usr/local/bin/vibetty

Prefer to compile it yourself? See Build from source below.

Configure the MQTT broker (once)​

VibeKeys and vibetty never talk to each other directly. Both connect to the same MQTT broker — a message relay — and everything (screen updates, keystrokes) flows through it:

VibeKeys (keypad)  ──>  MQTT broker  <──  vibetty (your computer)

Because both sides only make outward connections to the broker, there is no port forwarding or firewall configuration on your computer. Run vibetty setup once — it opens an interactive configuration screen and writes ~/.vibetty/config.toml. Then pick one of the two options below.

Option A: Built-in broker — simplest (device and computer on the same WiFi)​

vibetty can run the broker itself — no external service, no account:

[mqtt]
enable = true
builtin_broker = true
builtin_port = 1883      # built-in broker TCP port

The device connects straight to your computer, so on the setup page you enter mqtt://YOUR_PC_LAN_IP:1883 (see Step 2). Both have to be on the same network.

caution

The built-in broker has no authentication and is meant for your local network only — do not expose it to the public internet.

If you tried Option B first, clear the broker line before switching back. A non-empty broker always wins, so vibetty would start the built-in broker but still connect to the old address.

Option B: Cloud broker — use the device anywhere​

To use the device away from your computer (café, hotel, phone hotspot), point both sides at a broker they can each reach over the internet. For a single user, registering with a free MQTT cloud service is enough — e.g. EMQX offers free options:

[mqtt]
enable = true
broker = "mqtts://user:pass@broker.emqx.io:8883"

On the setup page you will later enter the same URL into the device.

Credentials live in the URL

There are no separate username/password fields — write them into the broker URL as mqtt://user:pass@host:port. Use mqtts:// for TLS (recommended whenever the broker is on the internet).

Run a shared session​

Pass your coding agent after -- — claude for Claude Code or codex for OpenAI Codex:

cd path/to/workspace/
vibetty -- claude   # Claude Code
vibetty -- codex    # OpenAI Codex

On Windows, use the .exe from PowerShell or Command Prompt:

cd path\to\workspace\
vibetty.exe -- claude

The MQTT button at the top of the vibetty screen shows conn once it has connected to the broker and started sharing.

You can append any claude parameter that you like:

# YOLO
vibetty -- claude --dangerously-skip-permissions

# Resume from last session in this workspace
vibetty -- claude -c --dangerously-skip-permissions
Let your agent start sessions for you

vibetty skill install --claude --codex installs a run-vibetty skill into Claude Code / Codex, so your agent knows how to start a shareable background session on its own.

To keep a session running in the background without occupying a terminal:

tmux new-session -d -s vibetty -c "$HOME/workspace" 'vibetty -- claude'

Build from source​

If you want to build from scratch, check out the vibetty GitHub repo and follow its build instructions.

Step 2: Connect VibeKeys Max to the broker​

  1. Boot VibeKeys Max and choose Keyboard from the boot menu — the configuration service is only advertised in Keyboard mode.
  2. Open the VibeKeys setup page in Chrome or Edge (Web Bluetooth requires one of these browsers, over HTTPS).
  3. Click Connect and select your VibeKeys Max from the list.
    • Can't find the device? It stops advertising once a host is already connected to it as a keyboard. Press the ACCEPT key on the device to re-start advertising, then try again.
  4. Add your WiFi networks — up to 8. List order is the priority order: at boot the device scans and connects to the first network in range, so add every network you use (office, café, home) once and the device follows you between places. Networks must be 2.4GHz (VibeKeys Max does not connect to 5GHz).
  5. Enter the MQTT broker URL — the same broker you gave vibetty:
    • Option A (built-in broker): mqtt://YOUR_PC_LAN_IP:1883
    • Option B (cloud broker): the exact same mqtts://user:pass@... URL you entered in vibetty setup.
  6. Fill in the ASR fields for voice input (see Voice Input), then click Save Changes.

The device stores everything locally and reconnects automatically after power cycles — wherever one of your saved WiFi networks is in range.

Step 3: Start vibe coding​

  1. Boot the device and choose Remote from the boot menu. It connects to the broker and opens the session picker, listing every vibetty session you have running.
  2. Pick a session: NEXT moves the focus, ACCEPT selects. Each row's label color reflects the agent's live state — white = working, orange = stopped / waiting; the focused row has a blue background.
  3. Drive the session from the remote terminal:
KeyAction
Rotary up / downScroll the terminal output
ACCEPTSend Enter
ESCSend ESC
NEXTSend ↓
BACKSPACESend Backspace
CUSTOMType /compact
YOLOShift + Tab (allow all edits)
Rotary push(Re)open the session picker to switch sessions
MICVoice input — see Voice Input
  1. Run several agents at once and switch between them any time with the rotary knob — no reconnecting.

Run vibetty as a Herdr plugin​

If you use Herdr, vibetty can run as a plugin instead of a separate command:

herdr plugin install second-state/vibetty

Then trigger the share action from the Herdr command palette (or bind it to a hotkey) to share the current agent pane — the vibetty status bar shows the live MQTT connection state. See the vibetty README for details.

Try it without hardware​

vibetty's HTTP server (toggle the HTTP button in its UI) exposes /mqtt_ws, a browser-based MQTT viewer with a terminal view, keyboard input, and session list. Use it to test your broker setup from a phone or laptop before the device is set up.