OpenRoom documentation

1. Quickstart

Host a session

1. Open the host console.
2. Sign in with Google. The hosted service uses the account to save agendas, enforce the 20-session daily quota and recover recent sessions on another device.
3. Create a session in deck editor or import a YAML agenda. You can save it in a folder in one of your spaces and add a new immutable version after each edit.
4. Start session. The console returns an 8-character session code and opens the host controls for that session.
5. Open the stage URL on the projector. It shows the code and a QR code pointing at the join URL.
6. Open a question, watch the response count, then reveal or advance. Use the phone remote if you want to move away from the laptop.
7. Export CSV or JSON, then end the session.

An assistant can validate the agenda, create the session and control an owned session through MCP. The browser console, phone remote, CLI and authenticated HTTP endpoint use the same session commands.

Join as a participant

1. Open the join page (join.openroom.app) on a phone or laptop.
2. Type the 8-character session code. It is case-insensitive and auto-uppercased. The alphabet is 23456789BCDFGHJKMNPQRSTVWXYZ: no vowels, no look-alike characters.
3. Scanning the QR opens https://join.openroom.app/?code=XXXXXXXX with the code filled in. A previous participant on the same browser resumes the stored session session.
4. Answer the current question. If answer change is enabled, you can change your answer until the host closes the question.
5. In the default identity mode, OpenRoom shows you a generated session handle. Keep it if you may need to rejoin from a different browser.
6. A tutoring session may instead be identified. It is then open only to people holding the access link the tutor issued for that context, and you appear under the name the tutor already wrote on it. You are still never asked to create an account or type a name.

2. Tutor-led sessions

OpenRoom provides the delivery surface for a human tutor. Codex, Claude Desktop or another external MCP client can read school material, work through what is needed and produce a typed outline. OpenRoom stores the resulting outline and presentation context. It does not receive the original files, retain the preparation conversation or replace the tutor.

Open the tutor workspace.

Preparation and delivery

1. Open the school material in the external preparation agent.
2. The agent drafts an Outline v1, validates it with outline_validate, then saves an immutable version through openroom_api.
3. Review the outline in the dedicated deck editor. The context list, deck list, create forms, edit forms, record page and deck editor are separate routes.
4. Launch the selected version. OpenRoom copies it into a session Durable Object and returns the host, stage and participant surfaces.
5. Move through semantic steps and interactions from the host console, a tablet, CLI, direct API or session_command.
6. After teaching, save compact outcomes, notes, homework and selected artifacts. This is a Notes, not a transcript.

Tutor workspace routes

Outline v1

The normative schema is packages/schema/schema/outline.schema.json. An outline contains metadata, semantic steps and the existing typed interaction definitions. Step kinds are title, statement, cards, steps, term, activity, timer, media, debrief, break and interaction. OpenRoom supplies the layout; outlines cannot contain CSS or screen coordinates. tutorNotes are stripped from participant and projector snapshots.

D1 holds contexts, deck metadata, immutable outline versions, compact records, trash state and deletion intents. Only a launched outline is copied into a session Durable Object. Original documents and model conversations remain outside OpenRoom.

Normal deletion moves a record to recoverable trash. An MCP or CLI client can request permanent deletion, but it receives only a short-lived URL. The signed-in tutor must open that URL and confirm the irreversible purge in a browser.

3. Session agenda format

A session agenda is a YAML or JSON document. The normative definition is the JSON Schema (draft 2020-12) at packages/schema/schema/session.schema.json. YAML and JSON forms of the same agenda are equivalent and covered by tests.

Top level

Defaults and per-interaction overrides

resultVisibility and allowAnswerChange can be set in defaults and overridden on any interaction.

Fields on every interaction

Type-specific fields

Display styles

The validator rejects a display value that does not belong to the interaction type. The first value listed is the default when display is omitted.

Validation errors

Validation returns stable error codes with a JSON path, so tooling can react to them: E_SCHEMA, E_DUPLICATE_ID, E_DISPLAY_MISMATCH, E_TOLERANCE_WITHOUT_CORRECT, E_OPTION_COUNT.

4. Full agenda example

This is examples/exit-ticket.yaml, a five-minute close for any session. All example agendas in the repository are validated in CI.

version: 1
meta:
  title: End-of-session exit ticket
  description: >-
    A five-minute close for any session: what stuck, what is still muddy, and how
    confident the class feels.
  locale: en
defaults:
  identityMode: anonymous
  resultVisibility: hidden-until-close
  allowAnswerChange: true

interactions:
  - id: understanding
    type: scale
    prompt: How well do you understand today's main idea?
    display: dots
    min: 1
    max: 5
    minLabel: Lost
    maxLabel: I could teach it
    allowDontKnow: true
    pedagogy:
      objective: Get a fast distribution of self-reported understanding.
      durationSec: 45
    notes: >-
      Watch the spread, not the mean. A bimodal picture means you have two
      classes in the session and need to split the next task.

  - id: key-takeaway
    type: text
    prompt: In one sentence, what is the most important thing you learned today?
    display: word-cloud
    maxLength: 200
    pedagogy:
      objective: Ask participants to retrieve the idea in their own words.
      followUp: Compare the cloud against your stated learning objective out loud.
      durationSec: 120

  - id: muddiest-point
    type: text
    prompt: What is still muddy? Name the thing you would ask if nobody could see who asked.
    display: list
    maxLength: 240
    pedagogy:
      objective: Surface confusion anonymously (muddiest point technique).
      durationSec: 120
    notes: >-
      Read them silently first. Pick the two most common and open the next
      session with those.

  - id: pace
    type: choice
    prompt: How was the pace today?
    display: bars
    options:
      - id: too-slow
        label: Too slow
      - id: about-right
        label: About right
      - id: too-fast
        label: Too fast
    resultVisibility: live
    pedagogy:
      objective: Calibrate the next session.
      durationSec: 30

  - id: questions-for-next-time
    type: qna
    prompt: Anything you want covered next time?
    display: list

5. MCP and repository CLI

MCP endpoint

POST /api/mcp provides a stateless Streamable HTTP endpoint. ChatGPT uses the OAuth flow. Other clients can use a personal API token created under Settings in the host console.

• outline_validate: validate an Outline and return its compiled interaction summary.
• session_validate: validate a SimpleSession or Session document.
• session_create: create a session and return the join URL, stage token and host token.
• session_status: read lifecycle state and participant count without results.
• session_results: read aggregate results without ballots or hidden answer keys.
• openroom_api: manage user-scoped contexts, decks, versions, records, launches and trash.
• session_command: apply host commands to an owned session, including outline navigation.

The browser, MCP, CLI and direct API call the same tutoring application services. Interactive sign-in and final confirmation of permanent deletion are the two browser-only operations.

Repository CLI

The openroom CLI lives in packages/cli. Every command accepts --json for a single machine-readable object on stdout. -h/--help prints usage; -v/--version prints the version. The package is private and has not been published for external installation. These commands require a source checkout.

Exit codes: 0 ok, 1 validation or command failed, 2 usage error.

Authoring (offline)

Running a session (hits the HTTP API)

session start writes .openroom.json in the working directory with the session id, code, host token and URLs. Later commands read it, so they need no flags. --url overrides the stored base URL.

Participant actions (answering, Q&A voting) are intentionally not CLI operations; the CLI holds a host capability, not a seat in the session.

6. HTTP API reference

The Worker serves JSON under /api/. The table covers the live-session and tutoring route groups. See openapi.json for the machine-readable catalog and individual authenticated routes.

Tokens

HMAC-SHA256 via WebCrypto, formatted base64url(payload).base64url(sig), payload { sessionCode, role, participantId?, exp }. Participant tokens expire after 6 hours; host and stage tokens after 12. The signing key is the TOKEN_SECRET secret. These capabilities grant access to one session and remain separate from the host's Google account and session cookie.

Command envelope

POST /api/sessions/ABCD2345/commands
Authorization: Bearer <token>
Content-Type: application/json

{
  "idempotencyKey": "6f1c...",
  "expectedRevision": 42,
  "command": { "command": "interaction.close", "interactionId": "understanding" }
}

The actor is derived from the token, never from the body. Host commands: session.start, session.end, session.freeze, session.unfreeze, session.advance, interaction.open, interaction.close, interaction.reveal, interaction.revote, interaction.undoRevote, session.theme, text.hide, text.unhide, qna.hide, qna.unhide, qna.stage, outline.next, outline.previous, outline.goto and outline.insert. Participant commands are answer.submit, interaction-block qna.vote, session-wide qna.ask and qna.upvote.

7. Live session behavior

• Session codes. 8 characters from 23456789BCDFGHJKMNPQRSTVWXYZ. The code is the session id. A code stops resolving once the session ends. Codes are not reserved or reusable across sessions in any way you should rely on.
• Idle auto-end. A session with no activity for 12 hours is ended by the Durable Object's alarm. The same alarm prunes stored idempotency keys.
• Retention after the end. Two deadlines run off the moment a session reaches ended, whether the host ended it or the idle alarm did. After 30 minutes the ballots are purged: every per-person answer and the participant roster are deleted, while the aggregates stay: counts, means and the wording of text and Q&A entries survive, with each entry's participant id replaced by purged-1, purged-2 and so on. The JSON export still works; the per-ballot CSV export returns 410 ballots-purged. After 24 hours the session is deleted outright; storage is wiped and the session id 404s exactly like a code that was never issued.
• Answer change. When allowAnswerChange is true, a participant's new answer replaces the old one, and the aggregate is recomputed. This is allowed until the interaction is closed, not until reveal.
• Countdown. A question with timerSec receives an absolute closesAt deadline when the host opens it. The Durable Object closes voting at that deadline. The timer does not award points.
• Participant recovery. Pseudonymous sessions assign a generated handle at join. A participant can submit the handle with the session code to recover the same participant id. Failed recovery attempts are limited per session.
• Session-wide Q&A. Participants can ask and upvote while the session is in the lobby or live state. A host can hide questions, show the list on stage or spotlight one question from the main console or Q&A desk.
• Tutor outline cursor. A launched Outline adds one semantic step cursor to session state. Moving to an interaction step closes the previous interaction and opens the referenced one; moving to a content step clears the active interaction. Stage and participant snapshots receive only the current safe step, while the host snapshot retains the full outline and tutor notes.
• Idempotent retries. Every command carries an idempotencyKey. The Durable Object stores key → result, so a retried request returns the original result instead of applying twice. The browser SDK generates the key and retries once on a network error with the same key. Re-opening an already-open interaction is a no-op success and does not bump the revision.
• Revisions. A monotonic session revision bumps on every applied mutation. Clients pass expectedRevision for optimistic concurrency and get 409 on conflict. On reconnect a client fetches the snapshot rather than replaying events.
• Transport. WebSocket notification first; the SDK falls back to polling (about 1.5 s while a question is open, 6 s idle, 15 s when the tab is backgrounded) after two WebSocket failures, and returns to WebSocket when it can.
• Moderation. A built-in English profanity blocklist sessions on every text and Q&A submission: substring and word-boundary matching over roughly 100 terms, after normalizing leetspeak (a→@ e→3 i→1 o→0 s→5) and stretched letters. A match marks the entry hidden; the participant is not told. The host can hide or unhide an individual entry. Panic freeze blocks all submissions and hides every participant text entry on the stage until unfrozen.
• Pre-reveal safety. Correct options, numeric correct values and tolerances, misconceptions and host notes are stripped from participant and stage snapshots before reveal. With the default hidden-until-close, the aggregate itself is also withheld. This is enforced in the snapshot layer and covered by dedicated tests.

8. Privacy facts

What is stored, for one live session, inside one Durable Object:

• The normalized session agenda.
• A server-generated participant id, join timestamp and handle for each participant in a session that uses handles. In a pseudonymous session the handle is generated and session-local; in an identified session it is the display name the tutor wrote on the context.
• One current ballot per participant per interaction, and the recomputed aggregate.
• Q&A entries and vote counts; hidden flags for moderated entries.
• Idempotency keys with their results, pruned on the hourly alarm.

The D1 control database stores host accounts and reusable work:

• Google subject id, email, display name and host session records.
• Saved agendas with immutable versions, spaces, folders, memberships and invitations.
• Presentation contexts, deck metadata, immutable Outline versions, compact session records, trash state and short-lived permanent-deletion intents.
• Context access links: for each link, the SHA-256 of the token, its visible prefix, its context, and its creation, expiry and revocation timestamps. The link itself is never stored and cannot be read back after minting.
• A session directory used for the 20-session daily quota, ownership checks and cross-device recovery of recent host controls.

OpenRoom does not store the original school documents supplied to an external preparation agent or the agent's model conversation. Outline provenance is labels and notes only.

Participants do not create accounts, and are never asked for a name, email or password in any identity mode. In an identified session the name shown is one the tutor authored on the context; nothing is collected from the participant. The browser apps contain no ads, analytics, tracking scripts, third-party fonts, CDNs or beacons. Application logs exclude participant answer text.

Context access links. A tutor can issue a link that lets one student or family read that student's own sessions and curated records. It is a revocable capability, not an account:

• It creates no user record, no sign-in session and no workspace membership, and it is rejected on every tutoring and workspace route. It works only on /api/learner/*.
• It reaches exactly one context. Students who share a tutor's workspace cannot read each other, and the context is taken from the link itself rather than from anything the caller sends.
• It is shown once at mint (only its hash is kept), expires after 180 days by default, is capped at ten live links per context, and the tutor can revoke it at any time.
• It never carries the tutor's private notes on a session, nor any past session code — a records link cannot become a way into a session.
• Only a space editor or owner can issue or revoke one. A presenter can run a session but cannot issue a credential.

Live-session retention:

• Ballots and the participant roster are deleted 30 minutes after the session ends. What is left is aggregate: counts, means, and text and Q&A entries whose participant ids have been replaced with purged-1, purged-2, … so no entry can be tied back to a person or to that person's other answers.
• The whole session (agenda, aggregates, idempotency keys, everything) is deleted 24 hours after the session ends.
• The per-participant CSV export is available for 30 minutes after the end and returns 410 after purge. The aggregate JSON export remains available until the session deletion deadline.

Host notes and pedagogy fields are host-only and are never sent to participant or stage clients. Tokens are session-scoped capabilities and expire (6 h participant, 12 h host and stage).

This is a description of the code, not a claim of compliance with any particular regulation. The hosted-service privacy policy and terms of use are the public legal pages.

9. Current availability

The hosted service sessions at openroom.app. Google sign-in is enabled there. The service has no billing system, and each signed-in host can create 20 sessions in a rolling 24-hour period.

The host application includes separate classroom-session and tutor-led session routes. The tutor workspace is at /host/#/decks. It includes presentation contexts, deck metadata, immutable outline versions, Outline Designer, synchronized delivery and compact Notes. It does not include original-document upload, video calling or a built-in heavy generation model.

OpenRoom does not offer public self-hosting yet. The source repository has not been published, no license has been selected, and no supported release or upgrade path exists. The internal deployment uses one Cloudflare Worker, a D1 control database and one SQLite-backed Durable Object per live session.

PowerPoint and Google Slides integrations are not implemented. The console shows inactive custom-branding controls marked “coming soon,” but the hosted service has no paid agenda. The 500-participant session target has not passed a load test.

10. Architecture

The Worker serves the marketing site, host console, participant app and projector view. It also handles Google OAuth, classroom and tutoring control-plane routes, session creation, participant joins and the machine interfaces.

D1 stores host accounts, sessions, API tokens, saved agenda versions, spaces, folders, collaborators, contexts, decks, immutable outline versions, compact Notes and the session directory. Ballot submission does not read or write D1. One SQLite-backed Durable Object owns each live session's agenda or launched session, lifecycle, session cursor, participant records, ballots, aggregates, moderation state and idempotency keys.

Clients send commands over HTTP and treat the HTTP response as the acknowledgement. Hibernation WebSockets carry revision notifications. A client that receives a notification fetches a role-scoped snapshot; polling takes over after repeated WebSocket failures.

  Browser host   MCP / CLI / API   Participant   Projector
         \             |                |             /
          +---------- Worker and static assets -------+
                         /                    \
                D1 business records       Deck Durable Object
                accounts, contexts         launched outline + cursor
                sessions, versions          ballots + aggregates
                records, session index         Hibernation WebSockets

R2 media storage and the public self-host adapter described in the PRD are not implemented.