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 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
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, 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:
/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:
API_SERVER_ENABLED=true
API_SERVER_KEY=<a long random string, e.g. from: openssl rand -hex 32>
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, which checks the download’s SHA-256 and leaves Gatekeeper to check the notarization:
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.
(
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:
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:
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
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:
/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.
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:
export SIPHON_TEAM_ID=<your team ID>
export SIPHON_BUNDLE_PREFIX=com.<yourname>.siphon
SIPHON_TEAM_IDis the 10-character Team ID of your Apple ID’s team. It’s theOU=value insecurity 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_PREFIXis 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
<your prefix>.watchkitapp (the iPhone app, <your prefix>, is allowed with it). Everything else
works without push.
5. Install the watch app
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 <id>, 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.
-
Start it. The command prints an address (like
192.168.1.23) and a 4-digit code, good for five minutes:/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.)
-
Wait for the watch. Once it has entered the code, this prints a 6-digit code and ends:
/Applications/Siphon.app/Contents/MacOS/siphon-desktop pair wait[You] The watch shows a 6-digit code too. Compare the two, digit by digit.
-
Pass the person’s answer on, and tap the same on the watch, in either order: the watch pairs only once both have answered.
/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 <the watch's name> 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 waitsays so), check the watch is on the same Wi-Fi and that Siphon is on in System Settings → Privacy & Security → Local Network, thenpair startagain for a new code. - No address, only 4 digits: a relay is connected (
statushasConnection: Connected), and pairing goes through it: on the watch choose Through the Relay instead of On This Network, then enter the 4 digits. pair cancelstops a pairing.devices remove <id>(the id is indevices 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.
/Applications/Siphon.app/Contents/MacOS/siphon-desktop account sign-up --email [email protected]
With the person’s address in place of [email protected]. 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.
/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 <email>. 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 verifyagain 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-upagain 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:
/Applications/Siphon.app/Contents/MacOS/siphon-desktop relay use-default /Applications/Siphon.app/Contents/MacOS/siphon-desktop account sign-up --email [email protected]
Through the browser instead. The same sign-in, approved on siphon.watch in a browser on this Mac:
/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-outtakes 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<relay address>:pbpaste | /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay use <relay address> --token-stdin /Applications/Siphon.app/Contents/MacOS/siphon-desktop relay onThe 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.
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.
/Applications/Siphon.app/Contents/MacOS/siphon-desktop <command>
| 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 <address> |
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 [<code>] |
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 <url> --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 <seconds>] |
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 <id> |
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 <name> [--model <id>] |
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": falsewith"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 verifytakes 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). 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.
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.