Starling Server — DEPRECATED

⚠️ This crate is deprecated. All roost server functionality has been moved to the starling core crate (v0.6.0+). Use starling::roost::server for background roost operations and starling::roost::store for message persistence.

This binary remains available for backward compatibility but will not receive new features. New development should use the starling launcher: starling roost create <name>.

For operators — running a roost

A roost is a persistent bird. It has no TUI and no GUI: you drive it entirely from the command line, and it stays running in a terminal (or as a service) to keep your community online.

Each roost lives under ~/.config/starling/roosts/<name>/ (Unix) or %APPDATA%/starling/roosts/<name>/ (Windows), with its own cryptographic identity key and sled database.

Install

Recommended: install the starling launcher, then:

starling install server

Or install standalone — no Rust or compiler needed:

Windows (PowerShell):

irm https://forgejo.hearthhome.lol/Saltfault/Starling-Server/raw/branch/main/install.ps1 | iex

Linux / macOS:

curl -sSfL https://forgejo.hearthhome.lol/Saltfault/Starling-Server/raw/branch/main/install.sh | bash

The installer places starling-server in your PATH. Upgrade: re-run the same command, or starling update server. Uninstall: install.sh --uninstall.

Quick start

# 1. Create a roost (mints its identity + database, prints the invite code)
starling roost create my-community

# 2. Start it — stays online until you press Ctrl+C
starling roost open my-community

# 3. Anyone joins from a client using the printed invite code:
#    starling join BIRD-...

Command reference

All roost commands take the roost's <name>.

Command	Status	Does
starling roost create <name>	✅	Create a roost: identity key + sled database. Prints the invite code
starling roost setup <name>	✅	Alias for create
starling roost open <name>	✅	Start the roost (blocks until Ctrl+C). Persists messages, serves history
starling roost close <name>	✅	Gracefully stops a running roost
starling roost destroy <name>	✅	Delete a roost and all its data
starling roost invite <name>	✅	Print the roost's invite code
starling roost status <name>	✅	Show roost info (identity, data path, and more)
starling roost doctor <name>	✅	Diagnose a roost's setup
starling roost logs <name>	✅	Show the roost's log location
starling roost members <name>	✅	List members with roles and bans
starling roost channel add <name> <ch>	✅	Add a channel (roost must be stopped)
starling roost channel remove <name> <ch>	✅	Remove a channel (roost must be stopped)
starling install server	✅	Install (or reinstall) the roost server
starling update server	✅	Update the server to the latest version
starling uninstall server	✅	Uninstall the server and remove config/roost data
starling help	✅	Print usage

Note: these starling roost … subcommands become available after starling install server. You always run them through the starling command; starling-server is the crate name (used as a library dependency, see below).

Running as a service

roost open blocks, which makes it a natural fit for a process supervisor. Point a systemd unit, a tmux/screen session, or your init system of choice at starling roost open <name>. Because iroh handles NAT traversal and relay fallback, no port forwarding or public IP is required — a roost behind home Wi-Fi still serves its community.

Backups are your responsibility. A roost's history and identity live only under its data directory — copy ~/.config/starling/roosts/<name>/ to back it up. There is no company keeping a copy behind the scenes; that's the point.

---

---

License

Apache 2.0