DocsSource

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,wren is valid and wren,tomo is rejected outright (not merely a second name for the same room).
  • A room "survives" a restart because its <name>.jsonl history 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.