Self-hosting your backend
We recommend Convex cloud, which is what setup uses unless you ask for something else. Your threads go to a Convex project in your own account, which keeps working while your Mac is asleep, sends your phone notifications, and needs nothing else installed. The free plan is enough for one Mac's ordinary use.
If you'd rather keep everything on your own machine, setup can run Convex's open source backend in Docker on your Mac instead, and reach it over Tailscale (or your own way, below). It's the same backend and the same features, with these limits:
- No phone notifications. The push relay only works with Convex cloud. The iPhone app shows what needs you when you open it, and its Settings say why nothing arrives.
- Your phone needs Tailscale on, as the backend is only on your tailnet.
- Nothing works while your Mac sleeps or Docker is stopped: the phone and the website can't reach the backend until it's back.
- Share links only open for people on your tailnet, so "Anyone with the link" means anyone on your tailnet.
You need Docker Desktop (or OrbStack), set to start when you log in, and Tailscale, logged in, with MagicDNS and HTTPS certificates on for your tailnet. Then run setup with --self-hosted, or ask your agent to (INSTALL.md says how):
./threadbear setup --self-hosted --yes
It starts the backend and its dashboard in Docker, on this Mac only, and puts them on your tailnet with tailscale serve: your threads' API on port 3210, your website on 3211 and the dashboard on 6791, all at https://<your Mac>.<your tailnet>.ts.net. Then it deploys Threadbear's backend and website there as it would to Convex cloud, and keeps them up to date the same way. Pair your phone and open the website from Settings › Phone & browser as usual.
The dashboard's sign-in asks for the admin key, which is in secrets/convex-self-hosted.env in Threadbear's data folder. Keep it to yourself: it can do anything to your backend. If the phone or the website can't reach it after a restart, run ./threadbear setup again: it starts the backend, or makes it again on the same data. docs/self-hosting.md in the repo has how it's put together, backing up, upgrading and taking it out.
On this Mac only, without Tailscale
If you won't use the phone, or you can't use Tailscale (your work keeps you on its tailnet, and Tailscale only has one on at a time), add --local:
./threadbear setup --self-hosted --local --yes
It's the same backend in Docker, on this Mac's 127.0.0.1 only: nothing on your network or any tailnet can reach it, and Tailscale isn't needed at all. That leaves out more:
- No iPhone app. Nothing off this Mac can reach the backend, so Settings › Phone & browser says why rather than showing a code, and there are no notifications.
- No second Mac joining this one.
- The website and share links only open on this Mac, at
http://127.0.0.1:13211. "Anyone with the link" means anyone using this Mac. - Nothing works while your Mac sleeps or Docker is stopped, as with the tailnet one.
The dashboard is at http://127.0.0.1:16791, with the same admin key. Running setup again keeps it local. If you get Tailscale later and want the phone, run ./threadbear setup --self-hosted --tailnet: it moves the backend onto your tailnet and your threads stay. --local moves it back.
At your own address
If your phone already reaches your Mac your own way (Caddy, nginx, cloudflared, your own Tailscale or a VPN), give setup the two https addresses your proxy answers on, and Threadbear leaves the rest to you:
./threadbear setup --self-hosted --yes \
--url https://threadbear.example.com \
--site-url https://threadbear-site.example.com
The backend stays on this Mac's 127.0.0.1, and your proxy points --url at 127.0.0.1:13210 and --site-url at 127.0.0.1:13211 (your website and share links). Setup checks both work, from this Mac and from inside Docker, before it carries on, and says which one didn't. Then pair your phone from Settings › Phone & browser as usual. That needs iPhone 1.0.5 or later.
The limits are the tailnet way's, except that Tailscale isn't needed: no phone notifications, nothing works while your Mac sleeps, Docker is stopped or your proxy is down, and share links open for whoever can reach your address. --local or --tailnet move it off your address, and your threads stay.