Scripts
Helper scripts under scripts/. Each is self-documenting (a -h/--help
flag, or a header comment printed on bad usage) — this page is a summary,
not a replacement for reading --help.
demo.sh
scripts/demo.sh [channel]
Builds tbase-server, mounts it in a temp directory, and opens two
Alacritty windows so you can chat with yourself: one tails the channel's
live stream, the other is a shell for sending. Everything (build output,
mount, server log) lives under a temp directory and is torn down on exit —
windows closed, mount unmounted, server stopped. channel defaults to
everyone; a name containing a comma opens a private channel instead (both
named users must be real accounts on the box).
This is the single-user demo — both windows run as you, so every message
is attributed to your own uid. The real cross-user setup needs mount -allow-other and separate logins (see getting-started.md).
Requires: go, alacritty.
shclient.sh
scripts/shclient.sh <channel>
scripts/shclient.sh -m <mountpoint> <channel>
scripts/shclient.sh <channel-dir>
A two-pane tmux TUI over one channel's shared nodes: the top pane replays
history then tails the live colorized feed (stream.human); the bottom
pane composes messages into send. There are no per-user directories —
every participant reads and writes the same channel files, and the server
attributes each message to the caller's uid.
<channel>resolves under the mount ($TBASE_MOUNT, or-m, default/var/tbase); a name containing a comma resolves underprivate/.<channel-dir>instead names a path that already holdssend/stream.humandirectly.- Uses
gumfor the input box if present, falling back to a plainreadloop otherwise (blank line submits). shclient.sh -hprints its own usage from its header comment.
It runs against a local mount, and there is deliberately no remote or Windows
counterpart to it: ssh <host> and run it on the server, where the mount and
tmux already are. Unlike voice.ps1/cast.ps1, which exist because your
microphone and speakers are on your machine, a chat client needs only a
terminal — and SSH is already carrying one.
Requires: tmux. Optional: gum.
voice.sh / voice.ps1
scripts/voice.sh <host> <channel>
scripts/voice.sh -m <mountpoint> <host> <channel>
Joins a channel's live voice call: wires your microphone and speakers to
the tbase-voice client, auto-detecting a capture/playback stack in this
order — pacat (PulseAudio) → pw-cat (PipeWire) → arecord+aplay
(ALSA) → ffmpeg — and printing the equivalent manual pipe one-liner
before running it. pacat is preferred even on a PipeWire host: raw PCM
playback paced by the server's mixer clock needs continuous adaptive
resampling against the local sound card, which the Pulse-compatible path
handles and pw-cat's raw path doesn't (it either xruns or free-runs at the
wrong pitch).
Env vars: TBASE_MOUNT (default /var/tbase), TBASE_VOICE_BIN (default
tbase-voice on PATH — this is a script-only convention; the tbase-voice
binary itself reads no environment variables).
scripts/voice.ps1 is the Windows counterpart, using ffmpeg's DirectShow
capture and ffplay for playback (Windows has no native raw-PCM output
device):
scripts\voice.ps1 tbase.example.com everyone
scripts\voice.ps1 -Device "Microphone (Realtek Audio)" wren@host tomo,wren
scripts\voice.ps1 -ListDevices # list detected DirectShow audio devices
It auto-detects the first DirectShow audio device if -Device isn't given,
and runs the three-stage pipeline through cmd.exe rather than native
PowerShell piping — PowerShell's pipe re-encodes/relines binary data, which
would corrupt the raw PCM stream.
Requires (voice.sh): the tbase-voice binary, plus one of the
capture/playback stacks above. Requires (voice.ps1): tbase-voice.exe,
ffmpeg/ffplay, an SSH client on PATH.
cast.sh / cast.ps1
scripts/cast.sh <host> <channel> <file>
scripts/cast.sh -m <mountpoint> <host> <channel> <file>
scripts/cast.sh -k radio|tv|cam <host> <channel> <file>
Broadcasts a media file to a channel, one shot start-to-finish: wraps
ffmpeg + tbase-cast so the file is the only thing you name. The profile
is guessed from the file's extension — a video container (.webm, .mkv,
.mp4, .mov, .avi, .ts) goes to the tv profile, everything else
(e.g. .mp3) to radio — or forced with -k. ffmpeg -re paces the read at
the file's own native frame rate, so it casts at real-time speed rather than
as fast as the CPU can transcode; radio gets raw S16LE/32kHz PCM, tv and
cam both get H.264/AAC muxed to MPEG-TS at the exact -muxrate
tbase-cast's tv/cam profiles require, cam with a shorter GOP than tv
(-g 15 vs. -g 50) to match its shallower listener buffer (see
broadcast.md). cam is never guessed from a file extension
— it's meant for a live camera feed running alongside a voice call, not a
file — so it's only reachable with -k cam.
Env vars: TBASE_MOUNT (default /var/tbase), TBASE_CAST_BIN (default
tbase-cast on PATH).
scripts/cast.ps1 is the Windows counterpart, same profile-guessing and
ffmpeg recipes, run through cmd.exe for the same raw-pipe reason
voice.ps1 is (see below):
scripts\cast.ps1 tbase.example.com everyone song.mp3
scripts\cast.ps1 -Kind tv wren@host tomo,wren screencap.mkv
Requires (cast.sh): ffmpeg, the tbase-cast binary. Requires
(cast.ps1): ffmpeg, tbase-cast.exe, an SSH client on PATH.
encrypt-send.sh / decrypt-tail.sh
A worked example of bolting end-to-end encryption onto tbase entirely at the client — see encryption.md for the full explanation.
printf 'hi tomo\n' | scripts/encrypt-send.sh /var/tbase/everyone \
-r <wren's age1...> -r <tomo's age1...>
scripts/decrypt-tail.sh /var/tbase/everyone wren.key
encrypt-send.sh <channel-dir> <age recipient args...> reads a message on
stdin, encrypts it with age -a, and writes the armored ciphertext to
send. Recipient arguments are passed straight through to age.
decrypt-tail.sh <channel-dir> <identity-file> reads history then tails
stream.bot, decrypting each message's data field with the given age
identity. A message that fails to decrypt (wrong recipient, garbled armor,
or a plaintext participant sharing the channel) prints [undecryptable]
rather than stopping the feed. Non-message events print as-is, since they
have no encrypted payload.
Requires: age (both scripts), jq (decrypt-tail.sh only).
record-demo.sh and userns-run.sh
scripts/userns-run.sh scripts/record-demo.sh [-k] [-o <dir>]
Records the landing page's hero demo: one person's terminal in a busy channel,
written as demo.mp4, demo.webm and a demo.jpg poster. wren reads the
channel in the top pane (cat stream.human) and sends from the bottom one
(echo ... > send) while tomo, ines, nadia and ci, a bot, post as
themselves from a timed script, each under a different real uid. tomo and
ines hold a reader open, so cat members shows them online; nadia and ci
only post, so they show offline. -o picks the output directory (default
site/); -k keeps the temp directory.
It needs no root. userns-run.sh runs a command in a new user namespace where
you are uid 0 and five more uids (1001-1005) are mapped from your /etc/subuid
and /etc/subgid range with newuidmap/newgidmap. Inside it,
record-demo.sh bind-mounts a private /etc/passwd and /etc/group that
define the members, runs tbase-server, and enters each pane as wren with
setpriv, so the server sees five different uids.
demo.tape is the vhs script that types wren's side;
its timings are matched to the at lines in record-demo.sh.
The kernel refuses to create a user namespace from a chroot. To work in one,
start the chroot from inside userns-run.sh, which needs util-linux's unshare
and nsenter, and shadow's newuidmap and newgidmap:
scripts/userns-run.sh chroot /path/to/root /bin/bash -c 'cd /repo && scripts/record-demo.sh'
record-demo.sh requires: mount, setpriv, tmux, vhs (and its ttyd),
ffmpeg, /dev/fuse, fusermount3, and a built tbase-server
(TBASE_SERVER=<path>, or ./tbase-server; go builds one if neither exists).
The emoji need the Noto Color Emoji font.