Siphon

Troubleshooting

Fixes for the common ways a Siphon setup goes wrong, with the commands to check each one.

Where to look first

/Applications/Siphon.app/Contents/MacOS/siphon-desktop status   # the setup checklist: what's done, what isn't, and why
curl -s http://127.0.0.1:8787/health # is the server answering?
ls ~/Library/Logs/Siphon             # logs: agent.log, server.log, desktop.log
pgrep -fl siphon                     # the app, its background agent and the server
scripts/login-items.sh status        # built from source: are the login items running?

status says in one go whether the server answers, whether the background agent is running, where the speech model is, which agent captures go to, whether the relay is on, who is signed in and whether it’s connected, and which devices are paired. A step that says [Needs attention] says what’s wrong. status --json gives the same to a script. A Siphon from before November 14, 2026 doesn’t have the command, and opens its window instead: Quickstart step 2 has the check (Setup commands).

Siphon.app shows every capture as it arrives, with its transcript and the agent’s reply.

Settings → Secure Relay has no Sign in button

The Mac is set to use a relay that isn’t one of Siphon’s (one you host, or one left from an earlier setup), and those have no account to sign in to. The page says so in place of the button, and siphon-desktop status says Relay server: … (not one of Siphon's: no account to sign in to). To sign in to a Siphon account, go back to Siphon’s relay first:

/Applications/Siphon.app/Contents/MacOS/siphon-desktop relay use-default
/Applications/Siphon.app/Contents/MacOS/siphon-desktop relay sign-in

In the window, that’s Reset to Siphon’s relay under Use a different relay (it clears Relay server and Account token): Sign in then shows.

The relay says “Not connected” or “Reconnecting”

/Applications/Siphon.app/Contents/MacOS/siphon-desktop status
  • Secure relay: off: siphon-desktop relay on.
  • Account: not signed in: siphon-desktop account sign-up --email <address>, with the person’s own address, or siphon-desktop relay sign-in in the browser (Quickstart, “Connect the relay”).
  • Sign-up: a code was emailed to …: the person reads the 6 digits in that email to their agent, which runs siphon-desktop account verify <code>. A code works for 10 minutes; after that, account sign-up again.
  • Away from home (optional): [Needs attention] This account has no active plan…: the person subscribes on the account page, and it connects by itself.
  • Connection: Reconnecting. <why>: the Mac can’t reach the relay. It keeps trying; the reason is the relay’s or the network’s.
  • Background agent: not running: open Siphon. The agent holds the relay connection, with the window open or closed.

Sending us a crash report or diagnostics

When Siphon crashes, the Mac keeps a short report of where in its code it happened, in ~/Library/Logs/Siphon/Crashes; the iPhone and watch keep theirs on the device. To send them:

  • Mac: Settings → About → Diagnostics → Review….
  • iPhone and watch: Settings → Diagnostics → Send Diagnostics.

Each shows exactly what would be sent (on the iPhone and watch, under Show the Report): the app’s version, the system and model, each crash’s place in the code, and on the iPhone and watch a log of launches and recordings starting and stopping (times and states only). Nothing goes until you choose Send to Siphon, which needs the device on a Siphon relay account (the Mac signed in, the iPhone or watch paired through Siphon’s relay). Otherwise, or if you’d rather, Save to File (Mac) or Share as File (iPhone and watch) and email it to [email protected]. Mention the reference Siphon shows after sending. What’s in a report, and what never is, is in the privacy policy.

Send crash reports automatically (next to it) sends new crash reports by themselves. It’s off unless you turn it on; the setup checklist and the iPhone and watch ask once.

curl on the Mac answers {"error":"unauthorized"}

Every route but /health needs the server’s token, from the Mac itself too: any app or user account on the Mac can reach 127.0.0.1, but only you can read the token file. Send it:

curl -s -H "Authorization: Bearer $(cat ~/.local/share/siphon/token)" http://127.0.0.1:8787/conversations

A JSON body also needs -H 'Content-Type: application/json', or the server answers 415.

Turning on debug logging

server.log has one line per event: <time> <LEVEL> [<part>] <message>, where the part is server, http, captures, stt, hermes, store or helper. By default it logs at info: startup, each capture’s progress, and every POST except audio chunks. SIPHON_LOG turns up the detail, in RUST_LOG syntax: debug for everything, or info,captures=debug,stt=debug for some parts. At debug, every request is logged with a number (req=12), and each audio chunk and its ack, each speech-to-text session and each hand-off to the agent shows its capture (capture=1a2b3c4d).

  • Built from source: SIPHON_LOG=debug scripts/login-items.sh install. Run scripts/login-items.sh install again without it to go back. For pnpm dev, SIPHON_LOG=debug pnpm dev.
  • Siphon.app: launchctl setenv SIPHON_LOG debug, then choose Siphon → Quit Siphon Completely (⌥⌘Q), which stops its background agent and server too, and open Siphon again. To go back, run launchctl unsetenv SIPHON_LOG and do the same.

tail -f ~/Library/Logs/Siphon/server.log follows it. Debug logging is chatty while you record (several lines a second), so turn it off once you’ve found what you were looking for.

Siphon didn’t update itself

Siphon.app from siphon.watch updates itself: its background agent looks for a new version when it starts and about once a day, and installs it once nothing is being recorded or answered. Settings → About shows the version, where an update is up to, and Check for updates. What it did is in the log:

grep 'update:' ~/Library/Logs/Siphon/agent.log | tail -20
  • “Siphon … is ready to install. Waiting for …”: it’s downloaded and checked, and goes in when the recording, the reply your agent is writing or the pairing it names has finished.
  • “Couldn’t update: …”: nothing was changed. It says why: the Mac was offline, or the download wasn’t one Siphon signed and Apple notarized (it’s never installed then). It tries again at the next look; Check for updates tries now.
  • “Siphon can’t replace itself in …”: Siphon.app is somewhere this account can’t write, or is being run from the disk image. Move it to Applications.
  • “Siphon … didn’t start on this Mac, so the version before it was put back”: the new version didn’t stay up after it was installed, so Siphon went back by itself and won’t install that version again. The next one is installed as usual.
  • “Siphon was updated to … This window is still the version before”: quit Siphon (⌘Q) and open it again.
  • “This is a development build” (or a copy that isn’t Siphon.app from siphon.watch): it doesn’t update itself. Built from source, update with git pull and pnpm desktop.
  • Automatic updates is off: Siphon only looks when you click Check for updates, and then offers Install.

Or update by hand, which always works: download Siphon from https://siphon.watch and drag it to Applications over the old one (Quickstart step 2 has the terminal commands), then open it.

pnpm dev fails: port 8787 is in use

A downloaded Siphon.app’s server or the server login item already holds the port. Quit Siphon.app, take its background agent out of launchd, then stop the agent and its server, in that order (launchctl bootout "gui/$(id -u)/watch.siphon.background"; launchctl bootout "gui/$(id -u)/com.corylogan.siphon.background"; pkill -f 'siphon-desktop --agent'; pkill -f 'siphon-desktop --server'; pkill -f 'Siphon.app/Contents/Resources/server'; the second is the agent of a Siphon downloaded before November 2026, the last one an older Siphon’s server). For the login item, either use the running one (scripts/login-items.sh install again after changing server code: it rebuilds the server), or run scripts/login-items.sh uninstall before using pnpm dev.

Built from source: the server stopped after git pull

The server is Rust now (crates/server); before, the login item ran node … apps/server/src/main.ts, which a pull removes. If server.log says it can’t find apps/server/src/main.ts, or scripts/login-items.sh status warns that the server login item is out of date, run scripts/login-items.sh install again: it builds the server and points the login item at it. Your captures and settings stay where they are.

pnpm watch: “No server token yet”

The server creates its token the first time it starts. Open Siphon.app once (step 2 of the Quickstart), then run pnpm watch again.

pnpm watch: “No paired Apple Watch found”, “The watch isn’t answering” or the install fails

  • Check that the watch is paired with an iPhone, unlocked, on the same Wi-Fi as the Mac, and has Developer Mode on. Then check that xcrun devicectl list devices lists it.
  • The wireless link to the watch is often slow to wake, and drops when the watch sleeps. pnpm watch checks the watch answers before it builds (“The watch isn’t answering”) and retries the install three times. Wake the watch and run pnpm watch again.
  • Signing errors: Xcode needs an Apple ID (Xcode → Settings → Accounts). If you use your own Apple ID, set SIPHON_TEAM_ID and SIPHON_BUNDLE_PREFIX before pnpm watch (Quickstart step 4). Don’t edit apps/watch/project.yml.

The watch or iPhone says “Pair with your computer first”

It isn’t paired, so it sends nothing and has no thread list to show. Pair it (Quickstart step 6).

A newly installed app opens on a set-up screen for this instead (Pair with your computer on the watch, Welcome to Siphon on the iPhone); you see the line above after tapping Not Now there. Pairing is then in Settings, and so is Show Setup Again, which brings the set-up screens back from the first one still to do: pairing, then on the iPhone the microphone, notifications and a first recording, and on the watch the Action Button.

It still records. What you say is saved on the device, with a level meter where the transcript would be (the transcript is made on your computer), and it says “Saved on this watch. Pair with your computer to send it.” and how many are waiting. Once it’s paired they go, oldest first. A recording that was waiting when you unpaired is kept the same way, and goes once it’s paired again.

If the device is almost out of storage it says “Not enough storage on this watch to save a recording” instead of recording. Nothing already saved is deleted to make room: pair it to send what’s waiting, or free some space.

If it says “Can’t read this watch’s pairing right now”, it is paired, but the saved pairing couldn’t be read (this can happen just after a restart, before the device is first unlocked). It reads it again by itself. What you record meanwhile is saved on the device, and goes once it can.

For development without pairing, a Debug build has a developer mode: Settings → Developer, the server’s address (siphon-server must listen on the network: SIPHON_HOST=0.0.0.0). It sends the token and your audio unencrypted, so only on a network you trust. The simulator uses its own loopback without it.

The watch or iPhone says its storage is almost full, or “Not all saved”

Every recording is also written to the device, so it isn’t lost if your computer can’t be reached. That needs storage.

  • “Storage on this watch is almost full”: it still records, and your computer usually gets it as you speak. If the computer can’t be reached, though, the recording may not be saved. Free some space on the device. (Unpaired, the device is the only place a recording can go, so it doesn’t record at all when there’s no room: see above.)
  • “Can’t save on this watch (storage is full). Keep Siphon open until this is sent”: storage ran out while you were talking. The rest is held in memory and still goes to your computer. If the computer got it, nothing was lost and there’s nothing to do.
  • “Not all saved”, or “Not all of it could be saved on this watch”: the computer couldn’t be reached either. The recording is whole for as long as Siphon stays open: it goes once the computer is back, and is saved as soon as there’s room. If Siphon is closed first, what had been saved is still sent: it arrives as a draft marked Cut short, which ends before you did. Read it and send it, or discard it and say it again.

A recording that ended because Siphon was closed while you were talking arrives the same way: a draft marked Cut short, with what had been saved until then.

Recordings kept on the device are listed under Threads, at the top: “1 recording on this watch” (or iPhone). Each says why it’s still there: waiting to reach your computer, only partly saved, or what the computer said when it wouldn’t take it. Send Now tries again. Swipe one left to delete it; that’s for good, as it hasn’t reached your computer.

Pairing on the home network doesn’t get to a code

The watch or iPhone talks straight to the Mac for this, at the address the Mac shows.

  • “Couldn’t reach a computer at that address”: check the address against the one on the Mac, and that both are on the same network (not a guest network, which keeps devices apart). If macOS asked whether Siphon may accept incoming connections, it needs Allow: System Settings → Network → Firewall → Options. The Mac listens on port 8788.
  • “Enter the address Siphon shows on your computer”: only a home network’s addresses are taken (like 192.168.1.23 or 10.0.0.5), in digits, not a name.
  • “Siphon on that computer is too old to pair on the home network”: update Siphon on the Mac, or pair through the relay.
  • “That computer isn’t showing that code”: the 4 digits expire after five minutes. Click Pair a device again for new ones (or run siphon-desktop pair start again).
  • The Mac says it can’t pair on your home network: it has no network address. Join your network and click Try again.

The watch or iPhone says “Away from home needs the relay”

It was paired on the home network with no relay, so it reaches the Mac at home only. What you said is kept on the device and sent once it’s back. Settings on the device shows Away from home.

  • To use it away from home, and to be notified when your agent replies, connect a relay on the Mac (Settings → Secure Relay → Sign in). The device picks it up the next time it’s home: no pairing again.
  • If you’re at home and it still says so, the Mac isn’t answering at the address the device knows: check the Mac is awake and Siphon is running. If your router gave the Mac a new address, pair again (Unpair on the device, remove it under Paired devices on the Mac, then Quickstart step 6). A device with no relay has no way to ask where the Mac went, so reserving the Mac’s address on your router avoids this.

Siphon stopped opening on the watch after a week

Apps installed with a free Apple ID expire after 7 days. Run pnpm watch again.

A message says “Saved. No agent connected yet.”

Nothing is chosen in Settings → Connectors, and none of the agents Siphon looks for answered: Hermes, Claude Code, Codex, in that order. Nothing is lost: the capture is kept on the Mac with its audio, and goes by itself once an agent answers (Siphon checks again every minute, with the next capture, and when you tap Retry now). Cancel drops it instead.

siphon-desktop connector list (and Settings → Connectors) says what each agent needs:

  • Hermes: API_SERVER_ENABLED=true and API_SERVER_KEY in ~/.hermes/.env, then restart Hermes. curl -s http://127.0.0.1:8642/health should answer. Siphon reads the key again at each check, so its own server needs no restart.
  • Claude Code: claude auth login.
  • Codex: codex login.

The server log (~/Library/Logs/Siphon/server.log) says which agent answers, or “no agent connected”, each time that changes.

Captures go to an agent that fails

An agent picked in Settings → Connectors (or the one a thread started with) is kept even when it stops answering: the message fails with that agent’s own error rather than going elsewhere. Fix the agent, or pick another one for new threads: Settings → Connectors, or siphon-desktop connector use <name> (connector list shows which are connected).

A message says “Saved. … is out of credit”

The model provider behind your agent (Anthropic, OpenAI, OpenRouter…) turned the message down because the account is out of credit. Nothing is lost: the message waits on the Mac, and so do any you send after it. Top up with the provider. Siphon tries again by itself after 5 minutes, an hour, then every 4 hours, and when the server starts; tap Retry now to try straight away, or Cancel to keep the message without sending it. The waiting messages then go in the order you sent them.

The watch or iPhone says “Nothing heard, saved anyway”

The Mac made out no words in the recording, but there was sound in it: something said quietly, whispered, or far from the mic. It wasn’t sent to your agent and isn’t in a thread, but the audio is kept. On the Mac, open Settings → Recordings to play it, have it transcribed again or delete it; it’s deleted by itself after 30 days. A recording with no sound in it at all says “Didn’t hear anything” instead, and isn’t kept.

A recording couldn’t be transcribed

Speech-to-text failed on it, on the Mac. The watch or iPhone keeps its copy and sends it again by itself, which is usually all it takes. The Mac keeps the audio it has too: Settings → Recordings lists it under Couldn’t be transcribed, where you can play it, delete it, or click Transcribe again. With words made out, it becomes a draft in your threads (open it there and send it, or discard it); it isn’t sent to your agent by itself. Its audio is kept, past the usual 30 days, until it has a transcript or you delete it.

A reply says “server restarted before the reply arrived”

The Mac’s Siphon server stopped (an update, a restart) while your agent was working on a message. When it comes back, Siphon sends that message to your agent again by itself, once, so you usually never see this. You see it when the server stopped a second time before that reply came: send the message again yourself. Your agent may have got the message before the first stop, and then gets it twice.

The watch says your computer is offline

A sleeping Mac can’t take captures, at home or through the relay. Siphon keeps the Mac awake while it’s on the power adapter: check Settings → Secure Relay → “Keep this Mac awake for Siphon” (On power adapter, Always or Never). The display still sleeps, but closing the lid puts the Mac to sleep anyway. pmset -g assertions lists Siphon’s assertion while it’s held, and ~/Library/Logs/Siphon/agent.log notes each time the Mac slept.

The first capture takes a long time

The first time the server starts, it downloads the speech model (about 600 MB) into ~/Library/Application Support/FluidAudio. Later starts load it from there.

The watch doesn’t stop recording, or stops too early

Recording ends after you’ve been quiet for about two seconds, or when you drop your wrist. “Quiet” is judged against the background, so steady road noise counts as quiet. Talk with the watch close to your mouth.

Thread titles are just the first few words

Short thread titles come from Apple’s on-device model (Apple Intelligence). If it’s off or still downloading, Siphon uses the first few words you said instead.