bambouville
bambouville / tessera / docs / troubleshooting

Troubleshooting

RSA keys are not supported

Tessera can't generate or import RSA keys: the current SSH stack can only offer the deprecated RSA/SHA-1 signature. Generate an Ed25519 key instead — every modern OpenSSH server accepts it. RSA keys left over from older versions are shown disabled.

Mosh won't connect

  • Is mosh-server installed on the server?
  • Can UDP reach the server? Some firewalls and most NATs block it; mosh needs UDP ports 60000–61000 by default.
  • Over a jump host: mosh's UDP can't traverse bastions. Tessera warns ("mosh is unreachable through the jump chain…") and falls back to SSH.

Forwarding refuses a local port

The iOS sandbox can't bind ports below 1024 — pick a higher local port. Local ports also can't repeat within one host. See port forwarding.

Forwarding is disabled on a Mosh host

With transport mosh and custom launch mode there is no SSH connection to carry forwards. Switch the launch mode to auto-tmux or named tmux — those keep an SSH side channel that forwarding rides on.

A connection sits at "connecting" or "starting tmux"

Wait twelve seconds: the launch overlay names the stage it's stuck on and offers edit host, retry, and back — no more indefinite spinner. If tmux itself is the problem (not installed, can't start, or the host's dotfiles already launch tmux at login), Tessera drops to a plain shell with a banner naming the reason. And if a session attaches but the screen stays blank, a banner says "press any key to wake it" — do that. See when a connection stalls.

tmux didn't pick up my changes

Environment variables and startup snippets only run when the tmux session starts. Kill the session on the server (tmux kill-session) and reconnect.

The files panel says the host key isn't trusted

The files bridge is a separate SSH connection with the same trust rules. Open a terminal session to the host, review the Unknown Host sheet, and accept the key — then reopen the panel.

The files panel doesn't follow my shell

Directory following needs OSC 7 from your shell. Use the panel's Enable follow — install shell integration button, then exec $SHELL or reconnect. Details in files.

Sessions to a WSL host freeze mid-output

The connection is fine but large bursts of output never arrive — an MTU mismatch on WSL2's virtual adapter, swallowing every big packet. See WSL MTU stalls.

Local network connections fail

iOS gates LAN access behind the Local Network permission. If you denied it, re-enable it in the Settings app under Tessera. The same permission is what lets nearby setup find your other device.

Nearby setup finds no devices

Both devices must have Tessera open on the setup screen, in the foreground, on the same network, with the Local Network permission granted on both. A version mismatch stops with an explicit "update Tessera on …" message. See nearby setup.

Handoff doesn't appear on the other device

Handoff is Apple plumbing: same Apple Account on both devices, Bluetooth and Wi-Fi on, and Handoff enabled in the iOS Settings app. A locked device stops broadcasting on purpose. Take-back for shared tmux sessions also needs tmux 3.2+ on the server. See continuity.

An agent card says "status unavailable"

Discovery found the agent, but precise state needs the per-host status hook — install or update it from the card. On Codex, the first integrated launch may also ask you to trust the hook via /hooks. See agent center.

Notifications don't arrive

Check the iOS notification permission (the bell settings sheet deep-links to it). Remember that background delivery is best-effort: iOS may suspend long background sessions. See notifications.

A purchase didn't carry over

settings → unlimited hosts → restore purchases re-checks your Apple Account — covering reinstalls, new devices, and the unlock included with an original paid-app purchase. See free & unlimited hosts.

Something else

settings → diagnostics → send to developer opens a pre-addressed mail with the diagnostics log attached — you see everything before tapping send. (It needs a mail account on the device; without one, use export log and send the file from any mail app.) Or file an issue at GitHub Issues. The log is redacted and only leaves your device when you send it.