DocsSource

Getting started

Requirements

Go 1.24+ and Linux with FUSE. The tbase-server binary is Linux-only; the tbase-voice and tbase-cast clients are plain Go and also build on Windows (see the Windows note in cli-reference.md).

Build

go build -o tbase-server ./cmd/tbase-server
go build -o tbase-voice ./cmd/tbase-voice   # optional: only needed to join voice calls
go build -o tbase-cast ./cmd/tbase-cast     # optional: only needed to broadcast or tune in to radio/tv

Set up the chat group

Chat participation is gated by membership in one Unix group (tbase by default, overridable with -group). The group must already exist when the server mounts — a missing group is a fail-fast error, not a silent no-op, because the server would otherwise come up unable to enforce who's allowed in.

sudo groupadd tbase
sudo usermod -aG tbase wren

A user's membership is checked dynamically on every request (via /etc/passwd and /etc/group, cached for at most one second), so enrolling someone new takes effect without restarting the server. See access-control.md for the exact rule (primary GID or supplementary membership).

Mount

tbase-server mount /var/tbase

mount is the only subcommand tbase-server has — there is no unmount subcommand and no config file, only flags. To unmount, use the ordinary FUSE tools (fusermount -u /var/tbase or umount /var/tbase), or just send the server SIGINT/SIGTERM: it unmounts on context cancellation and exits cleanly.

Flags

Flag Default Meaning
-allow-other false Expose the mount to other users (needs user_allow_other in /etc/fuse.conf) — required for multi-user chat
-data <dir> $XDG_STATE_HOME/tbase Directory for persisted channel history
-debug false FUSE protocol debug logging
-group <name> tbase Unix group whose membership defines chat participation
-voice-port <n> 61000 UDP port for the voice/radio/tv media plane (0 = OS-assigned ephemeral port)

For multi-user chat, run once with -allow-other. Each person then connects over SSH with their own login, and the server tags every message with the attested uid of whoever wrote it. If the server crashes or is restarted, just remount — channel history survives on disk; everything else (presence, topics, live calls) resets and needs no repair.

Defaults, precisely

  • Data directory: if -data is empty, it follows XDG: $XDG_STATE_HOME/tbase, else ~/.local/state/tbase, else $TMPDIR/tbase. This is the only directory tbase writes to on disk — one append-only <channel>.jsonl file per channel that has ever been used.
  • History retention: 10,000 messages per channel by default. Adjustable per-channel at runtime via ctl/retention (0 = unbounded) — see messaging.md.
  • Voice/media UDP port: 61000 by default. One well-known port serves every voice, radio, and tv session on the server, demultiplexed by a per-session id — one firewall rule covers all of it.

Send your first message

echo "hello" > /var/tbase/everyone/send    # send a message
cat /var/tbase/everyone/stream.bot         # watch the live feed (blocks like tail -f)

See filesystem-reference.md for the full tree and messaging.md for how send and the three stream formats work.