Skip to content
moshpit

Docs · Topic

Troubleshooting

For errors establishing an SSH or jump-host connection, see When it can’t connect. For everything after you are signed in, start below.

  1. Check iOS permissions and Moshpit’s switch: open Settings › Notifications in Moshpit. If iOS itself has notifications disabled for Moshpit, a banner tells you right at the top. Make sure Alert when an agent needs you is turned on.
  2. Verify pairing and send a test: open Set up a host on the connection, confirm both openssl and curl are present on the server and that outbound HTTPS can reach the push relay, and tap Send a test notification while keeping that screen open in the foreground.
  3. Remember the 30-second wait: “Needs you” pushes wait 30 seconds before firing so prompts you answer at your desk stay silent, and agents sitting idle at a prompt never send “Needs you”.

Codex ignores newly added hooks in ~/.codex/config.toml until you approve them inside Codex itself. Open codex on the host, run /hooks, and trust Moshpit’s four entries; see Set up a host.

  • On tmux: Home reads @moshpit_* options stamped onto panes by ~/.moshpit/moshpit-stamp.sh. Run Set up a host to install the hooks, then submit a new prompt in the agent so a hook event fires. Make sure your tmux session runs on the default tmux socket rather than a custom -L or -S socket.
  • On herdr: herdr reports state natively. If a banner warns that herdr on PATH and herdr server are on different versions, update the older side so the protocol matches.

“Finished” pushes omit what the agent answered

Section titled ““Finished” pushes omit what the agent answered”

Install jq on the host (sudo apt install jq, sudo dnf install jq, or brew install jq). Without jq, ~/.moshpit/moshpit-stamp.sh still sends completion pushes and turn durations, without extracting prompt text.

Screen wraps strangely when a desktop terminal is attached to tmux

Section titled “Screen wraps strangely when a desktop terminal is attached to tmux”
  • Desktop and phone switching each other’s window: upgrade tmux on the server to 3.8 or newer. On tmux 3.8+, Moshpit uses a grouped session so switching windows on your phone leaves your laptop terminal on its own window.
  • Two Moshpit devices on one window: when a window shows This window is sized for …, tap Use this device’s size to resize it to the device in your hand.
  • Transient redraw glitch: on Mosh, long-press the MOSH pill in the top bar and tap Repaint screen.

SSH succeeded and launched mosh-server, and UDP packets on 60000–61000 could not travel back and forth between your phone and the host. Open inbound UDP 60000–61000 on your server firewall and cloud security group, or turn off Use mosh in Edit connection when your current Wi-Fi network drops UDP; see Mosh.