Filesystem reference
Nothing under the mount is a real file. Every read and write is served live by the server, which resolves the caller's identity from the kernel-attested uid on every request (see access-control.md). Directory and attribute caches are kept short (1 second) so the tree stays live rather than going stale in the kernel's cache.
Root
/var/tbase/
├── users/ # one 0444 entry per known (group-member) user
├── everyone/ # the public channel — always present
└── private/ # private rooms — see below
| Path | Mode | Notes |
|---|---|---|
users/<name> |
0444 reg |
One entry per user currently in the chat group. Content is empty — this is a browseable roster, not a presence file (presence lives on each channel's members). |
everyone/ |
0555 dir |
The public channel. Every known (group-member) user can see and send to it. |
private/ |
0555 dir |
Contains only the rooms that currently exist — see below. |
private/<names>
A room's path is its membership: a sorted, comma-joined list of two or
more known usernames, e.g. private/tomo,wren or
private/ines,tomo,wren. There is no create step:
- Looking up any well-formed name whose members are all known users
materializes the room, for a caller who is one of its members. A
non-member gets
ENOENT— the room is invisible, not merely unreadable. ls private/only lists rooms that have a history file on disk (i.e. rooms that have been used at least once), filtered to ones the caller belongs to. A fresh mount lists nothing here even though any valid name still resolves on direct lookup.- A room's membership set has exactly one canonical path: names must be
strictly ascending with no duplicates, so
tomo,wrenis valid andwren,tomois rejected outright (not merely a second name for the same room). - A room "survives" a restart because its
<name>.jsonlhistory file does — there's no separate registry to rebuild.
Inside a channel (everyone/ or private/<names>/)
<channel>/
├── send # write a message (one open = one message)
├── stream.bot # live JSON feed (like tail -f)
├── stream.human # same feed, colorized, markdown-rendered
├── stream.llm # same feed, plain text, raw markdown (for LLM/agent readers)
├── history # persisted backlog, readable anytime
├── members # roster + presence
├── ctl/ # per-key channel settings
│ ├── topic
│ └── retention
├── file/ # file transfer
│ ├── send
│ ├── recv
│ └── members
├── voice/ # live voice call
│ ├── dial
│ ├── stats
│ └── members/
│ └── <name>
├── radio/ # single-writer audio broadcast
│ ├── self/
│ └── <owner>/
│ ├── dial
│ └── stats
├── tv/ # single-writer video broadcast, same shape as radio/
│ ├── self/
│ └── <owner>/
│ ├── dial
│ └── stats
└── cam/ # single-writer low-latency video-call cam, same shape as tv/
├── self/
└── <owner>/
├── dial
└── stats
| Path | Mode | Behavior |
|---|---|---|
send |
0220 reg |
Write-only. Every byte written between open() and close() becomes exactly one message, posted on close — so a multi-line block written in one open (a bot posting a build summary) becomes one message with its internal newlines intact, while echo/printf/shell clients (which open-write-close per call) keep their familiar one-message-per-call behavior. Capped at 64 KiB; a write that would exceed it fails EFBIG and the whole buffered message is discarded (bulk payloads belong on file/send). |
stream.bot |
0440 reg |
Read-only, blocks like tail -f. Live JSON feed — one compact object per line. Each open is its own subscription with its own bounded buffer, so one slow reader only drops its own messages. |
stream.human |
0440 reg |
Same feed, ANSI-colorized, with markdown (bold/italic/code/links/emoji) rendered server-side. |
stream.llm |
0440 reg |
Same feed, plain text, no ANSI, markdown left as raw source — for a reader that parses markdown itself. |
history |
0440 reg |
Finite, cat-able backlog (append-only JSONL on disk), trimmed to the last complete line so a read never races a torn write. stat reports the real on-disk byte count without materializing the backlog. |
members |
0440 reg |
Finite snapshot: topic: <topic> header, then one <name>\t<online|offline> line per member. Presence is derived from who currently has a stream file open — no ping/pong. |
ctl/topic |
0660 reg |
Reading it returns the channel's current topic; writing sets it. Any channel member may do either — see messaging.md. |
ctl/retention |
0660 reg |
Reading it returns the current history cap (0 = unbounded); writing a non-negative integer sets it. |
file/send |
0220 reg |
Write-only. Opening blocks until an audience is ready (see file-transfer.md), then streams bytes live to every claimed receiver — never buffered whole to disk. |
file/recv |
0440 reg |
Read-only. Blocks until a sender pairs with it, then streams the file out. |
file/members |
0440 reg |
Finite snapshot: one name per line, whoever currently has recv open — readiness, for a sender to check before firing. |
voice/dial |
0440 reg |
Read-only. Opening it runs the ACL check and mints a one-shot UDP session ticket {port, session, key}, then EOFs. See voice.md. |
voice/stats |
0440 reg |
Finite snapshot: per-talker ingest counters (underruns, resyncs, gaps, late). |
voice/members/<name> |
0660 reg |
Directory of live-call participants (not a flat file, unlike the three above): reading an entry gives your personal gain for that participant (default 1); writing sets it (0–4, 0 = personal mute). Your own name is never listed here — you cannot gain-control yourself. |
radio/self/, tv/self/, cam/self/ |
alias | A path alias that always resolves to your own broadcast slot, whoever you are. Never listed by ls, since your real name is already listed. See access-control.md and broadcast.md. |
radio/<owner>/dial, tv/<owner>/dial, cam/<owner>/dial |
0440 reg |
Read-only. Mints a session that is talker-only if you are <owner>, listener-only otherwise. Single-writer: a second concurrent owner dial is refused. |
radio/<owner>/stats, tv/<owner>/stats, cam/<owner>/stats |
0440 reg |
Finite snapshot of the owner's ingest counters (same four fields as voice), empty if nobody has streamed yet. |
ls radio/ (or tv/, or cam/) lists only the caller's own slot plus
any other member currently streaming — not every channel member — so
browsing doesn't surface a wall of silent, never-used slots.
See access-control.md for exactly who can see/send
where, messaging.md for the three stream formats and the
ctl/ knobs, file-transfer.md, voice.md, and
broadcast.md for the behavior behind each subtree.