What

Where

When

Size

GifOS site

GIFOS_URL, default https://gifos.app

every start

—

GifOS relay

GifOS's default relay, or GIFOS_RELAY

while in a broadcast (it only introduces peers)

—

Meeting Bot and Offline Captions apps

the GifOS store on GIFOS_URL (signed)

first join_broadcast

small

Whisper model

through the Offline Captions app

first transcription

about 77 MB

Kokoro weights

https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX at revision 1939ad2a8e416c0acfeecc08a694d14ef25f2231, or the mirror in GIFOS_KOKORO_URL

first start, kept in GIFOS_MCP_HOME/kokoro

about 92 MB; each file is checked against its pinned SHA-256

Chromium for Playwright

Playwright's download servers (npx playwright install chromium)

first start if missing, unless GIFOS_MCP_NO_INSTALL=1 or GIFOS_CHROME is set

about 150 MB

npm packages

the npm registry and GitHub (gifos-mcp-core)

install

—

Variable

Default

What it does

GIFOS_URL

https://gifos.app

The GifOS site. It must be 0.9.23b or newer.

GIFOS_RELAY

GifOS default

A custom relay (wss://…), added to meeting links.

GIFOS_BOT_NAME, GIFOS_BOT_PASSWORD

generated

The bot's name (what people see) and password. A bot.json that cannot be read is kept as bot.json.bad-<ms> and a new pair is generated.

GIFOS_STT_APP

offline-stt-whisper

The store app for speech to text. none turns transcription off.

GIFOS_MCP_HOME

~/.gifos-mcp

Browser profile, bot credential, meetings.json, schedule.json, transcripts, events.

GIFOS_HEADLESS

1

0 shows the browser windows.

GIFOS_CHROME

Playwright's Chromium

Another Chromium or Chrome binary.

GIFOS_TIMEOUT_MS

120000

How long to wait for GifOS steps such as joining.

GIFOS_MCP_HTTP_TOKEN

none

Bearer token for --http.

GIFOS_MCP_LAZY

0

1 starts the browser on the first tool call.

GIFOS_MCP_NO_INSTALL

0

1 never downloads Chromium; a missing browser is an error that says how to install it.

GIFOS_MCP_DEBUG

0

1 logs the GifOS console to stderr and adds caption state to status.

GIFOS_MCP_SHOTS

none

A folder for screenshots of the bot's screens.

GIFOS_TRANSCRIPT_POLL_MS

300

How often captions are copied from Meet Bot into the lines.

GIFOS_TTS_ENGINE

kokoro

kokoro (in this process) or none.

GIFOS_TTS_VOICE

af_heart

Kokoro's default voice for every line.

GIFOS_TTS_APP

empty

A GifOS store speech app instead of Kokoro in this process.

GIFOS_KOKORO_URL

https://huggingface.co

A mirror with the Hugging Face layout for the Kokoro weights. The pinned revision and hashes still apply.

GIFOS_TTS_URL, GIFOS_STT_URL

empty

HTTP stand-ins for speech and captions (testing). This process calls them; the page does not.

GIFOS_MAX_MEETINGS

4

Seated meetings at once. A join over the cap is refused; a scheduled join waits.

GIFOS_WORKERS

1

Stage B. More than 1 makes this process a supervisor and runs each Meet Bot in its own child process and Chromium. Worker 0 keeps the bot name and profile-bot. Worker n is its own bot, named <name>-wn, with profile-bot-wn. Lines that bot speaks in its room are stored as the bot's spoken lines under that name, not as speech from a person. A meeting stays on the worker that joined it. If a worker stops, its meetings go back to scheduled and the clock rejoins any order still in its window. A meeting with no order (join_meeting with no password, or start_meeting) is rejoined on the next clock tick too, unless end_meeting is called on it first. A room is joined once at a time: a clock tick and a start_meeting for the same room share one join, and end_meeting during that join leaves the seat as soon as it lands; if that leave fails, the meeting is live again on that seat with transcribing: false and raises one meeting.error ("The bot could not leave the room; call end_meeting again."), so a second end_meeting reaches it. A join that lands but whose transcription will not start leaves that room again and fails (the clock tries again on its next tick), so the bot is never seated twice in one room; if that leave fails too, the meeting stays live with transcribing: false and raises one meeting.error, and unmute or end_meeting reaches that seat. A worker that stops answering a heartbeat for 30s is killed and handled the same way, and so is one that has not finished booting (for example a stalled first download of the Kokoro weights, which the restart resumes) within 5 × GIFOS_TIMEOUT_MS; the join waiting on it goes to the next worker. A worker that keeps dying waits 1s, 2s, 4s, up to a minute before each restart, and joins (and the browser warm-up) go to another worker meanwhile; status shows restart_in_ms on that worker. A worker that is running but whose browser will not start is treated the same way: the join that found it out goes to the next worker, joins skip it for 1s, 2s, 4s, up to a minute before it is tried again, and status shows start_retry_in_ms and the start error on its row. A worker process that dies during a join (its browser goes with it) does not fail that join: it goes to the next worker with a free seat, once, so a room that takes down every worker it reaches costs at most two workers a restart. The clock does not join such a room again at once: it raises one meeting.error ("The room crashed the bot; trying again in N min.", with retry_in_ms) and waits 1 minute, then 2, 4, up to 30 between tries while the order is in its window, so the meetings it knocked off get their seats back and keep them. A start_meeting or join_meeting by hand waits on the same clock: on a room in its wait it fails at once ("The room crashed the bot; it can be tried again in N min.") without walking in, and a hand join that takes down every worker it reaches starts that wait too. The wait is kept in crashes.json under GIFOS_MCP_HOME (mode 0600), so a supervisor restarted within it still waits; an unreadable crashes.json is moved aside like schedule.json. While no worker has a free seat, an order due to join waits: it goes to waiting_for_capacity and raises one schedule.waiting event with reason: "worker" ("capacity" when the cap is reached), not an error every clock tick; if no seat frees before its end it is missed for capacity. A call to a worker that is still alive fails after 60s with no answer (a browser start or a join after 5 × GIFOS_TIMEOUT_MS); a join that ran out of time keeps its seat until the worker answers it (the bot may still be walking into the room; status shows late_joins on that row), so the worker is not given more rooms than its budget; one that lands after that is left at once, so no seat is held that nobody can reach, and one that fails frees the seat. A join that still has not answered one more join window later is checked against the worker's own Meet Bot room list: a room the supervisor does not hold is left (as above), and the seat is freed, so a join that never answers does not hold a seat until the worker dies. If the leave of a join that landed late fails, the room keeps its seat and is left again every 10s until it works; status shows stray_rooms on that worker's row meanwhile. A leave_meeting or end_meeting whose leave fails or runs out of time keeps the meeting live on its worker (the bot may still be in the room), so calling it again reaches the room; a late leave that lands, or Meet Bot answering that it no longer holds the room, frees the seat. A leave that still has not answered one more call window later is checked against the worker's Meet Bot room list: if the room is gone, the seat is freed; if the bot is still listed there, the seat stays taken. After a late leave landed or that check freed the seat, the next leave_meeting or end_meeting on that meeting ends it. status asks every worker at once and waits at most 3s for each; a worker that does not answer in time shows error on its row while the rest of status comes back. If the supervisor itself dies without shutting down (SIGKILL, out of memory), each worker sees its channel close, closes its Chromium, and exits, so no bot is left in a room that nothing can reach; a worker still booting (for example fetching the Kokoro weights) exits at once too, and so does one told to close while booting, keeping its part file for the next start. Each worker runs with a TMPDIR of its own, gifos-mcp-<tag>-w<n> under the supervisor's (the tag is named by GIFOS_MCP_HOME), emptied before each start and removed when the worker exits or close ends it, so the playwright-artifacts-* folder a worker killed under its Chromium could not remove does not pile up in /tmp; a worker leaving because its supervisor died removes its own. set_voice goes to every running worker at once; a worker that refuses it, misses it, or restarts gets the same settings again before its next join, and a running worker that refused is asked again every 10s until it takes them; meanwhile status shows voice: "pending" on its row.

GIFOS_WORKER_ROOMS

cap / workers, rounded up

Rooms per worker.

GIFOS_BOOTH_CAMERA_FILE

none

A .y4m or .mjpeg file the booth uses as its camera (a computer with no camera).

GIFOS_BOOTH_AUDIO_FILE

none

A .wav file the booth uses as its microphone (testing).

GIFOS_BOOTH_FAKE_MEDIA

0

1 gives the booth Chromium's test camera and microphone (testing).

Tool

Arguments

Returns

create_broadcast

title, host_password, start?, end?, timezone?, description?, visit_url?, stream?, host_name?

{ meeting_id, watch_url, invite }. Nothing goes live, joins or is sent.

open_booth

meeting_id or link, host_password, host_name?

Opens the host's seat on this computer, off air. Refuses a host password the broadcast was not made with.

go_live

meeting_id

Starts the live broadcast: this computer's camera and microphone go out to everyone watching.

play_video

meeting_id, path

Plays a video file live into the broadcast now; viewers see Prerecorded.

stop_video

meeting_id

Stops it.

set_start_time

meeting_id, start, timezone?

What early viewers see (countdown, Add to calendar). Empty clears it.

set_visit_link

meeting_id, url

The https Visit link on the picture and the ended card. Empty clears it.

end_broadcast

meeting_id

Ends the broadcast for everyone; viewers read that it ended; the booth closes.

booth_status

meeting_id

Open, on air, camera, microphone, video, watching, start time and Visit as the host page shows them.

close_booth

meeting_id

Closes the booth without the End step.

join_broadcast

link, topic?

Meeting Bot watches the broadcast and writes down what is said.

Tool

Arguments

Returns

wait_lines

meeting_id?, since?, timeout_ms? (≤ 30000), kinds?

Returns as soon as there is a line after since, or after timeout_ms. Pass next back as since. Lines addressed to the bot have to_bot: true.

tail_lines, tail_transcript

meeting_id?, since?, kinds?

The lines after since without waiting. Each line is {seq, ts, speaker, text, kind}; kind is speech, chat or spoken.

get_transcript

meeting_id

Plain text, one speaker: words line per caption, live and after the meeting.

say

meeting_id, text, voice?

Meet Bot says the line out loud now (Kokoro).

send_chat, share_content

meeting_id, text

A chat line as the bot (up to 2000 characters).

get_meeting_state, snapshot

meeting_id

Who is here; a PNG of the bot's page.

mute, unmute

meeting_id

Stop or restart note-taking.

leave_meeting, end_meeting

meeting_id

Saves the transcript, then the bot leaves. Other people stay.

schedule_meeting

link, room_password, start, end?

Stores the join order, including the room password, in schedule.json (mode 0600, written to a temp file then renamed, so a save cut short keeps the last good file; a file that cannot be read at start is kept as schedule.json.bad-<ms> and not overwritten). The bot joins one minute before start. A join that fails (not a crash, not a full pool) is tried again on every clock tick while the window is open, and raises one meeting.error ("The room could not be entered; trying again.") and one schedule.due for that order, not one per tick; after a join works, the next failure raises one again. Those events, and schedule.waiting, are once per window: an order moved to a new start or end (an order waiting for capacity goes back to upcoming) raises them again in its new window. end defaults to start plus 8 hours. The password is not returned.

list_schedule, update_schedule, cancel_schedule, import_schedule

see the schemas

Join orders. No passwords in results.

list_meetings, meeting_status, meetings_report, status, capacity_status

—

State, people, line counts, capacity. No passwords.

tail_events

since?

Connector events, including capacity.near, capacity.reached, and capacity.cleared. They are appended to GIFOS_MCP_HOME/events.jsonl (mode 0600); a torn last line left by a process killed mid-write is skipped and ended at the next start, so later events stay readable and no seq is handed out twice.

Symptom

Fix

The booth did not become the host of this broadcast

The host password is not this broadcast's, or the site is older than 0.9.23b.

The broadcast did not go live. This computer may have no camera

Use play_video, or set GIFOS_BOOTH_CAMERA_FILE.

This GifOS has no Rebroadcast

The site is older than 0.9.23b.

Kokoro: … does not match its pinned SHA-256

A download was cut or a mirror served other bytes. The file was removed; start again.

Chromium for Playwright is missing

Run npx playwright install chromium.

Anything else

GIFOS_HEADLESS=0 shows the browser windows.