Sessions
How session IDs are chosen, how rejoining works, and what happens when the connection drops.
A session is one broadcast of one directory. Its ID is the share link: there are no accounts, and anyone with the link can watch. Only the machine that created the session can change it.
Choosing the ID
biga start picks the session ID in this order:
--session <id>, if given.- The ID saved for this directory, which rejoins the same share URL.
- A new random 8-character ID, saved for next time.
An explicit ID must start with a letter or digit and contain only letters,
digits, _ and -, up to 64 characters.
Lifecycle
A session becomes active when biga start creates it. It stays active while checkpoints and heartbeats arrive. It ends when you stop the broadcast, or when no heartbeat has arrived for 45 seconds. An ended session becomes active again when biga start rejoins it, and is deleted by the retention sweep after the retention period.
Rejoining
On rejoin the CLI compares your local files with the server's copy and uploads only what changed. Local files are always the source of truth, so a crash, a server restart or a dropped connection is fixed by running the same command again.
◇ Rejoined biga (k3f9zq2a) — already in sync
◇ Rejoined biga (k3f9zq2a) — synced 1 changed file, 1.1 KBStopping a broadcast ends its session for viewers, who see the final state and a note that it ended. Starting it again reactivates the same link.
Who can write
When the CLI creates a session, the server hands it an owner token and keeps only a hash of it. Every later write (uploads, heartbeats, rejoining, ending) must present the token, so a link lets people watch and nothing more.
The token lives in ~/.biga/sessions.json. If it is lost (the file was
deleted, or you start the folder on another machine), the server refuses the
rejoin, and the CLI starts a new session with a new link:
▲ The server no longer accepts changes to session k3f9zq2a from this machine, so this broadcast gets a new link.--session <id> for a session another machine owns fails instead of taking it
over.
When the server is unreachable
The live panel switches to reconnecting — changes are buffered. Changes made
while the server cannot be reached are buffered and sent when it comes back,
and the panel says Back online..
Local state
The CLI keeps what it needs in ~/.biga (or $BIGA_HOME):
| Path | What it holds |
|---|---|
sessions.json | Each broadcast directory's session and its owner token. This is what keeps a project's link stable across restarts. Readable by your user only. |
control/ | Stop requests from biga stop. |
update-check.json | The latest release version, cached for a day. |