DocsSource

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 under private/. <channel-dir> instead names a path that already holds send/ stream.human directly.
  • Uses gum for the input box if present, falling back to a plain read loop otherwise (blank line submits).
  • shclient.sh -h prints 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.