Run your own Woodstar
Woodstar is built so that your identity is a key, not an account on someone's computer. That means you can hold your whole world — your posts, your messages, your people — on a machine you own. One small program is a complete instance.
The two-minute version
Grab woodstar-relay for your machine from
the
releases page (Linux amd64/arm64, macOS Apple silicon), or build it
yourself with Go 1.25+:
git clone https://amadan.net/woodstar/woodstar && cd woodstar
go build -o woodstar-relay ./cmd/relay
# run it — this is a complete instance, web app included
./woodstar-relay -addr :7071 -db my-woodstar.db -name my-instanceOpen http://localhost:7071, sign up, and you're the founder
of an instance of one. Everything works: posting, profiles, even the crypto
self-test page at /test/tests.html.
Staying reachable while your machine sleeps
A laptop instance goes offline. That's fine — point it at a
rendezvous: an always-on instance (like
woodstar.app) where you have an address.
./woodstar-relay -db my-woodstar.db -rendezvous https://woodstar.appFrom then on, automatically, about every thirty seconds:
| Up | Your posts mirror to the rendezvous, so your public presence never goes dark when your machine does. |
|---|---|
| Down | Replies, mentions and encrypted messages addressed to you — including anything that arrived while you were offline — stack at the rendezvous and sync down when you're back. Posts you made elsewhere (say, from your phone on the rendezvous itself) come home too. |
Catch-up is exact: sync follows arrival order at the rendezvous, so a week offline replays completely, in order, without duplicates. Messages stay sealed to your key — the rendezvous holds ciphertext it cannot read.
You need an address at the rendezvous first (sign up there, claim your username). Your key is welcome on both instances; that's the point.
Your own domain
An address is name@domain, verified by one JSON file. Put
any TLS proxy in front of your relay and your domain is your address home.
With Caddy, the whole config is:
you.example.com {
reverse_proxy 127.0.0.1:7071
}Claim your name on your own instance and you are
you@you.example.com — and if you ever move domains, your key
(and every petname anyone gave you) survives the move.
Honest limits, and what's next
- Pictures don't mirror yet — media lives where it was uploaded. Mirroring is on the roadmap.
- Your encrypted settings (petnames, follows — synced as sealed blobs) live on whichever instance your browser talks to.
- No inbound tunnel yet. Today your local instance
dials out; nothing can dial in. The next milestone is joining the
relay: your instance holds a connection open and gets a URL-addressable
spot (
you.woodstar.app) routed straight to your machine — no port forwarding, no fixed IP. - Search and notifications are optional satellite
services (
cmd/indexer,cmd/notify); a solo instance doesn't need them.
Relay flags
-addr | listen address (default :7071) |
-db | SQLite database path — this file is your instance; back it up |
-name | instance name shown in /info |
-rendezvous | always-on instance to sync with |
-sync-interval | how often to sync (default 30s) |
Protocol details live in DESIGN.md. Instances are boring on purpose: signed events in, signed events out.