# Troubleshooting

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

## Where to look first

```sh
/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](quickstart.md#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:

```sh
/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"

```sh
/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 [support@siphon.watch](mailto:support@siphon.watch). Mention the reference Siphon shows after
sending. What's in a report, and what never is, is in the
[privacy policy](privacy.md).

**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:

```sh
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:

```sh
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](quickstart.md)), 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.
