# Siphon > Siphon turns the Action Button on Apple Watch Ultra into a direct line to your AI agent. Press it and talk: your words appear live on the watch and on your Mac, go to your agent (Hermes today), and come back as a short reply on your wrist and a thread on your Mac. Speech-to-text runs on the Mac. Source: https://siphon.watch/llms.txt # What Siphon is > Voice capture from Apple Watch Ultra to the AI agent on your Mac. What it does, how the pieces fit, and what it needs. Siphon turns the Action Button on Apple Watch Ultra into a direct line to your AI agent. Press it and talk. Your words appear live on the watch and on your Mac. When you stop, the transcript goes to your agent, a short answer comes back to your wrist, and the whole exchange is kept as a thread on your Mac that you can carry on later. Siphon is in early testing. The Mac app is a public download (the current version is 0.1.0-1027; the [Quickstart](https://siphon.watch/docs/quickstart.md) installs it). The watch app is still built from source. ## Requirements - Apple Watch Ultra (watchOS 26 or later), paired with an iPhone - A Mac with Apple silicon running macOS 26 or later - An agent to send captures to. [Hermes](https://github.com/NousResearch/hermes-agent) works today. Claude Code and Codex can also answer inside Siphon using their local sign-in. ## How it works ``` Apple Watch Ultra ──audio──▶ Mac: siphon-server ──text──▶ your agent (Hermes) live transcript ◀──────── speech-to-text on the ──reply──▶ watch + Mac thread Neural Engine ``` 1. **Watch** (`apps/watch`): the Action Button starts recording in under a second. Audio streams to the Mac in half-second chunks, and the watch shows the transcript as it fills in. Recording stops after you've been quiet for about two seconds, or when you drop your wrist. Press again for the next thought as soon as one stops: it records straight away, while the one before finishes sending behind it. The iPhone's mic does the same. 2. **Server** (`crates/server`, on your Mac): stores each capture and runs speech-to-text locally. It uses NVIDIA Nemotron Speech Streaming 0.6B through FluidAudio, on the Neural Engine. 3. **Agent**: the server sends the finished transcript to your agent and asks for a one-line reply that fits a watch screen, followed by the full answer. 4. **Desktop app** (`apps/desktop`, Siphon.app): shows your conversations and live transcription, handles watch pairing, and keeps the Mac reachable when you're away from home. ## Choose your agent and model On desktop, open **Settings → Connectors → Agent & Model**. On iPhone, open **Settings → Agent & Model**. These settings choose the default for new threads on your host. On desktop, use the separate **Agent** and **Model** dropdowns in the composer footer; the model dropdown supports searching the selected agent’s catalog. On iPhone, tap the agent/model chip in the composer to open that thread’s settings. Changing the default does not change existing threads. The watch uses the thread’s choice, or the host default for a new thread. Siphon discovers the agents installed and signed in on the host, and reads their model catalogs. For Claude Code, install `claude` and run `claude auth login` on the host. For Codex, install `codex` and run `codex login` there. Both use your own login; credentials stay on the host. Use **Refresh** (desktop) or **Refresh agents** (iPhone) after changing setup (discovery results may be cached for up to 30 seconds). An unavailable agent shows why it cannot be selected. **Agent default** uses that agent’s own configured model; exact versions are shown on replies when the agent reports them. Until you choose, Siphon picks for you: a new thread goes to the first of Hermes, Claude Code and Codex that answers a check when the message is sent (Settings says "Picked automatically"). Being installed isn't enough: the agent has to be signed in and answer. Once you choose, your choice is kept, even if that agent stops answering; its messages then fail with its own error rather than going to another agent. With nothing chosen and no agent answering, captures are still transcribed and kept as threads. They say "Saved. No agent connected yet." on the watch, the iPhone and the Mac, and are sent by themselves once an agent is connected. The visible Siphon thread stays together when you change agent or model. The next message starts a fresh native session with a compact digest of the opening and recent exchanges. Long messages and older details can be omitted, so repeat any essential detail if needed. Matching agent/model choices reuse their native session. Messages already active or queued retain the choice they were sent with, and previous replies keep their original attribution. A failed request never silently switches to a different agent. Claude Code runs as a chat agent with its tools disabled. Codex runs with its read-only sandbox and no approval prompts. This is separate from handing work off to another app or repository. T3 Code appears as unavailable in the agent picker until a Siphon conversation connector is implemented. For coding tasks, the separate desktop **Hand off** action can [start a T3 Code task in a new worktree](https://siphon.watch/docs/t3-handoff.md), after you review the brief and choose a project. ## Approving what the agent wants to run When Hermes flags a command (a script run with `python3 -c`, a recursive delete), the turn waits for you instead of being refused. You see it on all three devices: - **Mac:** a card in the thread with the reason, the command, what the agent was doing, and every answer Hermes offers. **Always allow** asks again before it applies. - **iPhone:** a notification with **Approve once** and **Deny** (approving needs the phone unlocked). The thread shows the full command and offers **Allow for this session** when Hermes does. - **Apple Watch:** a notification and a card with **Approve once** and **Deny**. A notification shows the command itself. If one shows only "Hermes needs your approval", **Approve once** doesn't approve: "Open the thread to approve" appears instead, and tapping it opens the thread, where you see the command and answer. The first answer from any device counts. The others then show how it was answered, for example "Approved once from Watch". If nobody answers within 10 minutes, it's denied and the agent is told why. The thread records every answer. ## Privacy - Speech recognition runs on your Mac. Audio goes from your watch to your own Mac, not to a Siphon cloud. - Raw audio is deleted after 30 days. Transcripts and threads stay until you delete them. A recording that couldn't be transcribed keeps its audio until it has been, or you delete it. - At home, the watch talks to the Mac directly over your network, using sealed (encrypted) requests once it's paired. Pairing happens on your network too, with no relay: you compare a code on both screens. - Away from home, an optional paid relay carries those same sealed requests. It forwards them without being able to read them, and your Mac still does all the work. Notifications when your agent replies, or when your Mac goes offline, come through the relay too: without one, the watch and iPhone get none, and what you say away from home waits on the device until it's back. - A Mac signed in to a relay account sends a daily summary of usage counts (never content). You can turn it off in Settings. The [privacy policy](https://siphon.watch/docs/privacy.md) has the details. ## Pricing - **At home:** free. Self-hosted on your Mac and your network, pairing included. - **Away from home, and notifications:** a paid relay subscription (planned). A watch or iPhone paired at home picks it up when you add it, with no pairing again. ## Next - [Quickstart](https://siphon.watch/docs/quickstart.md): set Siphon up on a Mac and a watch. - [Troubleshooting](https://siphon.watch/docs/troubleshooting.md) - [Privacy policy](https://siphon.watch/docs/privacy.md) --- # Quickstart > Set Siphon up on a Mac and an Apple Watch Ultra, from the Mac app download and the watch app's source. Written so a coding agent can run it step by step. This guide installs the Mac app, builds the watch app from source and gets a capture from your watch to your agent. Each step has a command and a check. Steps marked **[You]** need a person at the Mac or the watch. **For agents:** run the steps in order and run each check before moving on. When you reach a **[You]** step, stop and tell the user exactly what to do, then wait for them to confirm. Don't print secrets (the server token, `API_SERVER_KEY`). Every command is safe to run again. Once the Mac app is installed (step 2), set it up with its own commands rather than asking the person to click through Settings: `siphon-desktop status` says where setup is up to, and [Setup commands](#setup-commands) lists the rest. Three things stay with the person, and you never do them for them: approving the Mac in the browser, comparing a pairing code with the watch, and answering macOS's prompts. ## 0. Check the Mac ```sh sw_vers -productVersion # 26.0 or later uname -m # arm64 node -v # v22 or later corepack enable && pnpm -v # 12.x xcodebuild -version # Xcode with the watchOS 26 SDK xcodegen --version || brew install xcodegen ``` If something is missing, install it before going on. Apple silicon and macOS 26 can't be worked around. Node, pnpm, Xcode and XcodeGen are for building the watch app (steps 3 and 5). ## 1. Connect an agent Siphon finds your agent by itself. It uses the first of these that answers on this Mac, in this order: [Hermes](https://github.com/NousResearch/hermes-agent), Claude Code, Codex. If Claude Code (`claude auth status`) or Codex (`codex login status`) is signed in, there's nothing to do. To use another one than the first, choose it once the Mac app is running (step 2). A choice is never changed: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop connector list # the agents, which are connected, and where captures go /Applications/Siphon.app/Contents/MacOS/siphon-desktop connector use codex # hermes, claude or codex: one that's connected ``` Settings → Connectors does the same in the window. Hermes needs its API server on, in `~/.hermes/.env`, and a restart of Hermes: ```sh API_SERVER_ENABLED=true API_SERVER_KEY= ``` **Check:** once the Mac app is running (step 2), `siphon-desktop status` (the command is in step 2) has a line `Your agent: [Done] Captures go to …` naming the agent, and `connector list` marks it `(captures go here)`. The setup checklist's **Your agent** step and Settings → Connectors say the same. No agent yet? Go on anyway. Captures are transcribed and kept as threads that say "Saved. No agent connected yet.", and they're sent by themselves once one is connected: nothing to restart. ## 2. Install the Mac app The Mac app is signed and notarized by Apple, and it brings its own server and speech-to-text. It needs a Mac with Apple silicon running macOS 26 or later. The current version is 0.1.0-1027. The person can download it from https://siphon.watch and drag Siphon to Applications, or you can install it from the terminal, in one of two ways. With [Homebrew](https://brew.sh), which checks the download's SHA-256 and leaves Gatekeeper to check the notarization: ```sh brew install --cask counterbeing/siphon/siphon open /Applications/Siphon.app ``` Or step by step, with every check written out. The block below is the whole install: it works out the machine, reads the release list for the current version, checks the download's SHA-256, checks that the disk image and the app are signed by Siphon's team and notarized by Apple, then installs and opens Siphon.app. Run it as one command. It stops at the first step that fails, and on a machine Siphon doesn't run on it says so in one line and installs nothing. Set `SIPHON_APPS_DIR` to install somewhere other than /Applications. ```sh ( set -eu # 1. This machine. Siphon runs on a Mac with Apple silicon and macOS 26 or later. if [ "$(uname -s)" != Darwin ]; then echo "Not supported: there is no Siphon for $(uname -s) yet. It needs a Mac with Apple silicon and macOS 26 or later." >&2 exit 1 elif [ "$(sysctl -n hw.optional.arm64 2>/dev/null)" != 1 ]; then echo "Not supported: Siphon needs a Mac with Apple silicon. This one has an Intel processor." >&2 exit 1 elif ! [ "$(sw_vers -productVersion | cut -d. -f1)" -ge 26 ] 2>/dev/null; then echo "Not supported: Siphon needs macOS 26 or later. This Mac has macOS $(sw_vers -productVersion)." >&2 exit 1 fi platform=mac # 2. The current release for this platform: its version, its file name, its SHA-256. work=$(mktemp -d) cd "$work" curl -fsS -o latest.json "https://download.siphon.watch/latest-$platform.json" version=$(plutil -extract version raw -o - latest.json) file=$(plutil -extract file raw -o - latest.json) sha256=$(plutil -extract sha256 raw -o - latest.json) echo "Installing Siphon $version" # 3. Download that file from the same place, and check it is the one the release list names. curl -fsS -o Siphon.dmg "https://download.siphon.watch/$file" echo "$sha256 Siphon.dmg" | shasum -a 256 -c # 4. Check it is Siphon's: signed with Siphon's Developer ID (team 3V94DAXZ2J) and notarized # by Apple. The disk image first, then the app copied out of it. signed='anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] exists and certificate leaf[field.1.2.840.113635.100.6.1.13] exists and certificate leaf[subject.OU] = "3V94DAXZ2J" and notarized' codesign --verify --strict --check-notarization --test-requirement="=$signed" Siphon.dmg mkdir image hdiutil attach -nobrowse -readonly -noautoopen -mountpoint image Siphon.dmg >/dev/null 2>&1 || diskutil image attach --mountOptions nobrowse --readOnly --mountPoint image Siphon.dmg >/dev/null ditto image/Siphon.app Siphon.app hdiutil detach -quiet image 2>/dev/null || diskutil eject image >/dev/null codesign --verify --strict --deep --check-notarization --test-requirement="=identifier \"watch.siphon.desktop\" and $signed" Siphon.app # (Build attestation: when Siphon's releases carry one, the command that checks it goes here.) # 5. Install it and open it. A copy that is already there is replaced; quit it first. apps=${SIPHON_APPS_DIR:-/Applications} osascript -e 'quit app "Siphon"' 2>/dev/null || true rm -rf "$apps/Siphon.app" ditto Siphon.app "$apps/Siphon.app" open "$apps/Siphon.app" cd / && rm -rf "$work" ) ``` To check a download made some other way: version 0.1.0-1027 is https://download.siphon.watch/Siphon-0.1.0-1027.dmg, and its SHA-256 is `c0f3b4480d707607d6dcab508d6de4887ed1fc8bef3f72e45a28484e4acd6b71`. Siphon.app starts its background agent (watch pairing and replies, even with the window closed), which starts Siphon's server on `127.0.0.1:8787`. The first start creates the server's token at `~/.local/share/siphon/token`, which the watch build reads, and downloads the speech model (about 600 MB) into `~/Library/Application Support/FluidAudio`. The window opens on the **Set up Siphon** checklist: starting at login, the speech model (how much is downloaded and the time left), your agent, pairing, the relay and the first capture, each ticking itself off as it's done. You can record before the model is ready: captures wait and are transcribed once it is. Close the checklist any time; **Help → Set Up Siphon** (or Settings → About → **Set up Siphon**) brings it back. **Check:** ```sh spctl -a -vv /Applications/Siphon.app # accepted, source=Notarized Developer ID curl -s http://127.0.0.1:8787/health # answers within a few seconds of opening the app ls ~/.local/share/siphon/token ``` The Siphon window is open, and the checklist's **Speech model** step says **Ready** once the download is done. Logs are in `~/Library/Logs/Siphon` (`agent.log`, `server.log`). From here on, `status` is the check for every step. It prints the checklist as the window shows it, and changes nothing: ```sh grep -q 'relay use-default' /Applications/Siphon.app/Contents/MacOS/siphon-desktop && echo "has the setup commands" /Applications/Siphon.app/Contents/MacOS/siphon-desktop status ``` ```text Server: answering at http://127.0.0.1:8787 Background agent: running Runs in the background: [Done] Siphon starts at login, … Speech model: [Not yet] Downloading: 42% of about 600 MB. Your agent: [Done] Captures go to Claude Code. Pair your watch or iPhone: [Not yet] Not paired yet. … Away from home (optional): [Optional] Not needed at home. … ``` Each step is `[Done]`, `[Not yet]`, `[Needs attention]` (with what's wrong) or `[Optional]`. `status --json` gives the same as one JSON object (`steps.speech.state` is `done`, `waiting`, `failed` or `optional`). Run the first line before the first command, and go on only if it prints `has the setup commands`: a Siphon from before November 14, 2026 doesn't know them, and opens its window instead of answering. Update it with the install commands above. **Updates are automatic.** Siphon's background agent looks for a new version when it starts and about once a day, downloads it, checks that it's signed by Siphon and notarized by Apple, and installs it once nothing is being recorded or answered. The agent and server switch to the new version on their own; a Siphon window that was open says so in Settings → About until it's reopened. Nothing to do, and nothing to run. Settings → About has the version, **Check for updates**, and the **Automatic updates** switch (on unless turned off; off, Siphon only looks when asked, and offers **Install**). `agent.log` says what it did, on lines starting `update:`. Updating by hand still works, and is the fallback: run the commands above again (or drag the new Siphon.app over the old one) and open it. The background agent and server that were running switch to the new version on their own. Siphon's background agent and server also start at login, without the window, so the watch can reach the Mac after a restart. Once the checklist's **Runs in the background** step has said so, macOS shows a "Background Items Added" notification: that's this. The switch is Settings → Secure Relay → "Start Siphon at login", or from the terminal: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop login-item status /Applications/Siphon.app/Contents/MacOS/siphon-desktop login-item on # or: off ``` **[You]** If it says macOS is waiting for an OK, the person turns Siphon on in System Settings → General → Login Items & Extensions. `login-item on` opens that page for them, and the checklist has **Open Login Items**. Tell them the "Background Items Added" notification is Siphon's. ## 3. Get the source The watch app is built from source, which is private during early testing. ```sh git clone https://github.com/counterbeing/siphon.git ~/Code/siphon cd ~/Code/siphon pnpm install ``` If the clone fails with a permission or "not found" error, the user isn't in early testing yet. Stop here and point them to the waitlist at https://siphon.watch/#waitlist. ## 4. Get the watch ready [You] - The Apple Watch Ultra is paired with an iPhone, unlocked, and on the same Wi-Fi as the Mac. - Developer Mode is on: on the watch, Settings → Privacy & Security → Developer Mode. The watch restarts. - Xcode is signed in to an Apple ID: Xcode → Settings → Accounts. The watch app is signed with the Siphon team by default. If you build with your own Apple ID, set two variables before step 5 instead of editing any files: ```sh export SIPHON_TEAM_ID= export SIPHON_BUNDLE_PREFIX=com..siphon ``` - `SIPHON_TEAM_ID` is the 10-character Team ID of your Apple ID's team. It's the `OU=` value in `security find-certificate -c "Apple Development" -p | openssl x509 -noout -subject` (open Xcode → Settings → Accounts → Manage Certificates once if there's no certificate yet). - `SIPHON_BUNDLE_PREFIX` is a reverse-DNS prefix of your own: bundle IDs are unique across Apple, so the default one is taken. Every Siphon bundle ID and the shared Keychain group derive from it. The watch app asks for push notifications, which only a paid Apple Developer team can sign. With a free Apple ID, step 5 fails with a signing error about the Push Notifications capability. Even with a paid team, the hosted relay can only push to Siphon's own app IDs, so with your own `SIPHON_BUNDLE_PREFIX` reply and "Your computer is offline" notifications don't reach your watch or iPhone. Getting them means running your own relay with your APNs key and `RELAY_APNS_TOPIC` set to `.watchkitapp` (the iPhone app, ``, is allowed with it). Everything else works without push. ## 5. Install the watch app ```sh pnpm watch ``` This builds the app (a Debug build, with the server token baked in for development; the token is only used if you type a server address in its developer settings), installs it on the paired watch and launches it. The watch's wireless link can be slow to wake: if the install fails, ask the user to wake the watch and run it again. With a free Apple ID, installs expire after 7 days, so re-run `pnpm watch` to renew. **Check:** the command ends with `Installed and launched on `, and Siphon is open on the watch. It shows **Pair with your computer**: until it's paired it sends nothing, and keeps what you record on the watch. (**Not Now** there goes to the record screen, which says "Pair with your computer to send what you say. Until then it's saved on this watch.") ## 6. Pair the watch with the Mac This needs no relay: with none connected, the Mac pairs the watch on your home network. The watch has to be on the same network as the Mac. If macOS asks whether Siphon can find devices on your local network, the person clicks **Allow**. Pairing takes three commands, with a step for the person after each of the first two. 1. Start it. The command prints an address (like `192.168.1.23`) and a 4-digit code, good for five minutes: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop pair start ``` **[You]** On the watch: Siphon → **Pair** → **On This Network**. Enter the address, tap **Next**, then enter the 4 digits. (If the watch is on its record screen instead, it's Settings (gear) → **Pair with Computer**.) 2. Wait for the watch. Once it has entered the code, this prints a 6-digit code and ends: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop pair wait ``` **[You]** The watch shows a 6-digit code too. Compare the two, digit by digit. 3. Pass the person's answer on, and tap the same on the watch, in either order: the watch pairs only once both have answered. ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop pair confirm matches # the same six digits on both /Applications/Siphon.app/Contents/MacOS/siphon-desktop pair confirm differs # different digits, or the watch shows an error instead of a code ``` **[You]** On the watch: **Matches** if they're the same, **Doesn't Match** if not. **For agents:** the 6-digit code is the one thing here you can't check, because you can't see the watch. Show the person the code `pair wait` printed, ask them whether their watch shows the same six digits, and run `pair confirm` with what they say. Never run `pair confirm matches` on your own: matching codes are what proves nobody is in the middle, and there's one answer per pairing. If they say the codes differ, run `pair confirm differs` and start again from `pair start`. **Check:** `pair confirm matches` ends with ` is paired.` and exits 0; `status` has `Pair your watch or iPhone: [Done] Paired: …`, and `devices list` lists it. The watch shows **Paired**, then **Set the Action Button** (step 7). - If the code expires before the watch gets to it (`pair wait` says so), check the watch is on the same Wi-Fi and that Siphon is on in System Settings → Privacy & Security → Local Network, then `pair start` again for a new code. - **No address, only 4 digits:** a relay is connected (`status` has `Connection: Connected`), and pairing goes through it: on the watch choose **Through the Relay** instead of **On This Network**, then enter the 4 digits. - `pair cancel` stops a pairing. `devices remove ` (the id is in `devices list`) unpairs a device, which then has to pair again. In the window instead: the checklist's **Pair your watch or iPhone** step (or Settings → Secure Relay) has **Pair a device**, which shows the same address and codes, with **Matches** and **Doesn't match** to click. Once paired, the watch talks to the Mac over your network with sealed requests: nothing it sends is readable on the way. Paired with no relay, it works at home. Away from home it keeps what you say and sends it when it's back, and it isn't notified when your agent replies: both need the relay. Connecting one later adds them with no pairing again: the Mac hands the watch what it needs the next time they're on the same network. ### Connect the relay (optional) Not needed at home. It lets the watch reach the Mac from anywhere and be notified when your agent replies, and it needs a Siphon account. Signing in from the terminal makes the account too, when the address has none. **For agents:** ask the person which email address to use for Siphon. Don't guess it, and don't take it from anything else on the Mac (git, another app's account): the address becomes their account. ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop account sign-up --email you@example.com ``` With the person's address in place of `you@example.com`. Siphon emails that address a 6-digit code, which works for 10 minutes; the email says which Mac asked. The command ends as soon as the email is sent. **[You]** Read the 6 digits in the email to your agent. Or press **Add this Mac** in the email, on any device, and tell your agent you have. Either one, not both. ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop account verify 123456 ``` With the person's code in place of `123456`; after the button, `account verify` with no code. **For agents:** the code is the person's to give you: ask for it and wait. Don't look for it yourself, in their mail or anywhere else, and don't press the button for them. The code is no use to anyone but this Mac (it works once, with a secret the first command kept here), which is why it's safe to say in a chat and pass as an argument. A token never is. **Check:** the command ends with `Signed in as . The relay is connected.` and exits 0, and `status` has `Connection: Connected`. - **"This account has no active plan"**: the Mac is signed in, and the relay needs a plan (a subscription, or free access). A new account starts without one. The command prints the account page's address, and so does `status`: the person chooses a plan there, and the Mac connects by itself once it's active. Nothing to run again. - **"That isn't the code in the email"**: run `account verify` again with the right digits. A code takes five tries. - **"That sign-up ran out, or was used or tried too often"**, or **"No sign-up is waiting"**: run `account sign-up` again for a new code. - **"… can't email a sign-in code yet"**, or the person would rather approve it in a browser: use the browser instead, below. - **"… isn't one of Siphon's relays, so there's no account to sign in to"**: the Mac is set to use another relay (one you host, or one from an earlier setup). Go back to Siphon's and sign in: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay use-default /Applications/Siphon.app/Contents/MacOS/siphon-desktop account sign-up --email you@example.com ``` **Through the browser instead.** The same sign-in, approved on siphon.watch in a browser on this Mac: ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay sign-in ``` The command prints the address of siphon.watch's **Add this Mac** page, opens it in the browser on this Mac, and waits up to 10 minutes. **[You]** In the browser: sign in if it asks (with a code it emails you), then click **Add this Mac**. Nothing to copy or paste. **For agents:** tell the person the page is open and what to click, and leave the command running until it ends: stopping it cancels the sign-in. Don't approve the Mac for them, in a browser you control or any other way. `--no-open` only prints the address, which works only in a browser on this Mac. It ends as the emailed code's does: the same check, and the same word on a plan. - **Signing out:** `siphon-desktop relay sign-out` takes this Mac off the account, removes its token from the Keychain and turns the relay off. - **A relay you host yourself** (docs/RELAY.md) has no account to sign in to. Give the Mac its address and its Mac token, then turn the relay on. The token comes on standard input, so it's never on a command line or in the shell's history: copy it, then run this with the relay's address (it starts with `https://`) in place of ``: ```sh pbpaste | /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay use --token-stdin /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay on ``` The same takes a token made by hand on your account's Devices page (siphon.watch/account/devices, **Add a Mac by hand**), with the relay address that page shows next to the token. In the window instead: the checklist's **Away from home** step → **Sign in** opens Settings → Secure Relay, where **Sign in**, **Sign out**, the **Use secure relay** switch and **Use a different relay** do the same. An open window shows what a command changed within a second. ## 7. Set the Action Button [You] On the watch: Settings → Action Button → Control → **Talk to Siphon**. Siphon shows the same path on its **Set the Action Button** screen once it's paired, and that screen goes away by itself the first time a press starts a recording. A watch without an Action Button shows **Tap to talk** instead: tap **Talk**, or add Siphon to the watch face (a complication that opens it) or **Talk to Siphon** to Control Center. ## 8. Try it [You] Press the Action Button and say something to your agent. The first press asks for the microphone: allow it, and it starts recording. Talk with the watch close to your mouth. Drop your wrist when you're done, and the capture is sent once you stop talking. **Check:** the words appear on the watch and in Siphon.app as you speak, and the agent's short reply shows up on the watch. The checklist's last step, **Action Button, then a first capture**, ticks itself off when the capture arrives. If anything goes wrong, see [Troubleshooting](https://siphon.watch/docs/troubleshooting.md). ## Setup commands Siphon.app's own binary does from a terminal what Settings does in the window. An older Siphon doesn't have them: step 2 has the check. ```sh /Applications/Siphon.app/Contents/MacOS/siphon-desktop ``` | Command | What it does | | --- | --- | | `status` | The setup checklist: the server, the speech model, the agent captures go to, starting at login, the relay (on or off, which one, who is signed in, the connection), paired devices and a pairing under way. Changes nothing. | | `account sign-up --email
` | Signs this Mac in to a Siphon account with a code emailed to the person, and makes the account if the address has none. Sends the email and ends. | | `account verify []` | Finishes it: with the 6 digits the person read out, or with no code once they've pressed **Add this Mac** in the email. | | `relay sign-in [--no-open]` | The same through the browser: prints the **Add this Mac** address, opens it, waits up to 10 minutes for the person to approve. | | `relay sign-out` | Takes this Mac off the account, forgets its token, turns the relay off. | | `relay use-default` | Goes back to Siphon's own relay: clears the address and token set with `relay use`. | | `relay use --token-stdin` | A relay you host, or a Mac token made by hand. The token is read from standard input. | | `relay on`, `relay off` | The **Use secure relay** switch. | | `pair start` | Starts pairing a watch or iPhone: prints the 4-digit code to enter on it, and with no relay connected the address to enter first. | | `pair wait [--timeout ]` | Waits for the device (5 minutes unless told), then prints the 6-digit code to compare, and stops. Run again after an answer, it gives the outcome. | | `pair confirm matches`, `pair confirm differs` | The person's answer to "does your device show this code?", passed on. One answer per pairing. | | `pair cancel` | Stops a pairing. | | `devices list` | The paired watches and iPhones, each with its id. | | `devices remove ` | Unpairs one. It has to pair again to come back. | | `connector list` | The agents Siphon knows, which are connected (and what the others need), and which one captures go to. | | `connector use [--model ]` | Sends new threads' captures to that agent, as choosing it in Settings → Connectors does. It has to be connected. | | `login-item status`, `login-item on`, `login-item off` | The "Start Siphon at login" switch. Siphon.app from siphon.watch only: an app built from source says why not. | | `help` | This list. | Every command: - takes `--json`: one JSON object a line on stdout, the last line the result (`"ok": true`, or `"ok": false` with `"error"`). A command that waits (`relay sign-in`) prints a line first (`"event": "waiting"`, with the address to open); - exits 0 when it did what it was asked or there was nothing to do, 1 when it couldn't, with one line on stderr saying why, and 2 when it wasn't asked properly; - is safe to run again; - never prints a token, and never takes one as an argument. (The code `account verify` takes isn't one: it works once, for 10 minutes, and only from the Mac that asked for it.) They read and write what the window does (the settings file, the Keychain item, the background agent), so the two can be used together. `pair` and `devices` talk to the background agent, which runs whenever Siphon has been opened since login: if a command says it isn't running, run `open -a Siphon` and try again. `connector` talks to Siphon's server on this Mac, which the background agent runs. **The person's steps, which no command does:** giving their email address, and the code Siphon emails it or a press of the email's button (`account sign-up` only sends the email); approving the Mac in the browser (`relay sign-in` only opens the page and waits); comparing the 6-digit pairing code with the watch (`pair wait` shows it and stops; step 6), macOS's Local Network and Login Items prompts (`login-item on` opens the page, the person allows it), and everything on the watch or iPhone. An agent passes these on and waits for the person. It never answers for them. ## Building the Mac app from source instead To work on Siphon itself, run the Mac side from the checkout instead of the download (steps 0 to 3 first; also install [Rust](https://rustup.rs)). Stop the downloaded app first: quit Siphon.app, take its background agent out of launchd (it would start again), then stop the agent before its server (the agent would start the server again), so port 8787 is free. Once the login items below are installed, the downloaded Siphon's agent leaves this Mac to them at login. ```sh osascript -e 'quit app "Siphon"' 2>/dev/null || true launchctl bootout "gui/$(id -u)/watch.siphon.background" 2>/dev/null || true launchctl bootout "gui/$(id -u)/com.corylogan.siphon.background" 2>/dev/null || true # a Siphon downloaded before November 2026 pkill -f 'Siphon.app/Contents/MacOS/siphon-desktop --agent' || true pkill -f 'Siphon.app/Contents/MacOS/siphon-desktop --server' || true pkill -f 'Siphon.app/Contents/Resources/server' || true # an older Siphon's server pnpm stt:build # speech-to-text: apps/stt/.build/release/siphon-{stt,title,clean} pnpm dev # builds and runs the server; long-running. Stop it before login-items.sh install pnpm desktop # builds Siphon.app (a few minutes the first time) and opens it SIPHON_ROOT="$PWD" scripts/login-items.sh install # builds the server; it, the agent and the app at login scripts/login-items.sh status ``` With the login items installed, the app runs from `~/Applications/Siphon.app` and the server from the checkout (`crates/server/target/release/siphon-server`, which `install` builds: run it again after changing server code); a downloaded Siphon.app then leaves the server to them. Without an agent, start the server with `SIPHON_DESTINATION=echo pnpm dev` and Siphon replies with what it heard. --- # 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](https://siphon.watch/docs/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
`, 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 `. 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. `: 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](https://siphon.watch/docs/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: `