# Running a pitch

- URL: https://getroomi.com/docs/running
- Built: 2026-10-26

Once a build is live, running the pitch is the publisher's side of the room:
seeing it as a viewer will, making a link for each person, what happens when
they open it, reading and answering what they say, changing what is live, and
closing a link or a room. This page follows a pitch from the first preview to
the last link, and says what a viewer sees at each point, including every way
a room can turn them away.

## See it as a viewer first

**Preview as viewer**, at the top of every project in the app, opens the room
in a new tab exactly as a viewer sees it, marked with a bar across the top:

> Preview — this room as a viewer sees it. Nothing you do here is recorded;
> commenting, reacting and answering are off.

It works on every plan and needs no link. The app asks the platform for a
one-time pass, good for two minutes and only for a member of the project's
workspace, and the room spends it on arrival. The preview has its own copy of
a container demo, so you can run the tour and every scenario without touching
a viewer's.

If nothing opens, the browser blocked the new tab: allow pop-ups for the app
and choose **Preview as viewer** again.

## Making a link per viewer

On a paid plan, each viewer gets a link of their own. The link is who they
are: you name the person when you make it, and everything they do in the room
is filed under that name. Each link also gets its own copy of a container
demo.

Free has no private links ([Free rooms](#free-rooms)).

### In the app

The project's **Links** tab has the form:

- **Viewer's name**: up to 80 characters. It is what the room calls them and
  what your pipeline shows.
- **Email (optional)**: for your own records, and where **Send this for me**
  emails the link if you tick it. The room does not use it.
- **Expires**: in a week, in two weeks (the default), in a month, in three
  months, or never.

**+ New link** makes it and shows its address, to copy and send. If the viewer
loses it, **Copy link** beside their name (on the Links tab, their pipeline
card or their journey) copies the same address again, and the project's
history records who copied it. A link made before 1 October 2026 kept only a
hash of its key, so it offers **Reissue link** instead: the same viewer and
everything they did, under a new address, with the old address stopping at
once.

### From the CLI

```sh
roomi link "Priya Shah" --email priya@example.com --expires 14
```

```text
  A link for Priya Shah, until 2026-10-13:
  https://corner-for-bullring.getroomi.app/l/q3JxV8mZ0tQeR5wLk2HbNA
  Send it to them. If it is lost, `roomi link copy "Priya Shah"` shows it again.
```

`--expires` takes a whole number of days, 1 to 365; without it the link does
not expire. `--project <slug>` names the project; without it, the one named in
`pitch.json` here.

### From Claude, or the API

The connector's `create_link` tool makes one, and Claude asks before it does
([Deploying from Claude](https://getroomi.com/docs/claude)). Through the API it is `POST
/api/projects/:projectId/links`:

```json http
{ "viewerName": "Priya Shah", "viewerEmail": "priya@example.com", "expiresInDays": 14 }
```

The reply carries the link and its `url`. No list returns an address;
`POST /api/links/:linkId/reveal` returns one link's again, and is recorded.

## Sending it

Roomi sends nothing unless you ask it to. Tick **Send this for me**
beside **+ New link** (it appears once the email is an address), add `--send`
to `roomi link`, or say yes when Claude asks, and Roomi emails the
viewer their link for you, once, from its own address and under the name you
chose ([Having it sent for you](https://getroomi.com/docs/sharing#having-it-sent-for-you)).
Otherwise no email and no invitation goes: copy the address and send it
yourself, the way you would send anything else to that person.

The address is the viewer's key. When they open it, the room takes the token
out of the address bar at once and keeps them in with a cookie of its own, so
the key does not end up in a bookmark or a screenshot. Anyone holding the
address can open the room as that link, which is why every browser is asked
who it is ([Are you Priya?](#are-you-priya)).

## When the viewer arrives

### Are you Priya?

Every browser that opens the link is asked who it is before the room opens,
the first one included. A link forwarded before Priya opens it is then not
filed under her:

> **Are you Priya Shah?**
> Northwind made this link for Priya Shah. If it was passed on to you, say who
> you are, so Northwind knows who is looking.

- **Yes, I'm Priya Shah** carries on as her.
- **No, I'm someone else** asks for a name and an email, and adds that person
  under the same link. You see them on the link's pipeline card and in its
  Activity as forwarded: "opened Priya Shah's link and said they were someone
  else". The buying group becomes visible instead of forwarded silently.

The same question meets Priya herself on a second device, and on her own
browser once her session there has lapsed ([Sessions](#sessions)). A phone
joined from the room's QR code is not asked: it carries on as whoever showed
the code. If you ticked **Require an email to view** ([Asking for an
email](#asking-for-an-email)), Priya is not asked for the email you made the
link with; someone else gives theirs as they say who they are.

Where the project records what viewers click inside the demo, the same page
asks one more question, with neither answer chosen: "Can Northwind also see
what you click in the demo?", **Yes** or **No thanks**. Under it, on its own
line: "By entering, you accept Roomi's viewer terms." A browser that
sends Global Privacy Control or Do Not Track is not asked, and nothing is
recorded ([What the viewer is asked](https://getroomi.com/docs/screens#what-the-viewer-is-asked)).

Each session that answers yes is counted. When more than one has, the link's
pipeline card and its Activity say "Opened as Priya Shah in 3 separate
sessions". That can be Priya on another day or device, or someone the link was
passed to; the room cannot tell which.

### Not Priya?

Someone who answered yes sees **Not Priya Shah?** beside the name in the
room's header. It asks for a name and an email, as "No, I'm someone else"
does, and adds that person under the link. What that browser did as Priya in
its current session (its visits, comments, answers, reactions and an email it
gave) moves to them. Nothing Priya did in any other browser moves.

Everyone under one link shares that link's copy of a container demo.

### Asking for an email

On a paid plan, the project's **Settings** tab has **Room access**, with
**Require an email to view**. With it on, a viewer types an email before the
room shows anything:

> **Your email, to open this room**
> Northwind asks for an email before showing this room. Nothing is sent to it,
> and it is not checked.

Without it, a link opens straight away, and a viewer is asked for an email
once, the first time they comment or react.

No email is checked: an address is only what someone typed, and the only
email Roomi sends a viewer is their link, when you ask it to
([Sending it](#sending-it)). The app marks these emails as unverified. The email you gave
when you made the link is the named person's once they answer **Yes**;
anyone else types their own.

### Sessions

A viewer's visit is held by a cookie on the room's address, which lasts twelve
hours. Within it, reloading, coming back to the tab, or opening the room again
in the same browser carries on as the same person. After it, they open their
link again. The room's own address, without the link, opens nothing for
someone whose session has lapsed, unless the project is listed, when it opens
the public room.

## In the room

What a viewer can do, and what you learn from it:

- **The tour**, when the build has a `story`: a card on the stage offers it on
  arrival and runs nothing until asked. Each step says what to notice, shows
  its app, rings what to look at and, on a container build, runs its calls on
  the viewer's own copy. **Explore freely** leaves it at any point, and the
  rail's outline starts it at any step. [Writing the tour](https://getroomi.com/docs/story).
- **The apps**: one tab each along the top when there is more than one, each
  in its device frame. The viewer can change the frame, go **Full screen**,
  open the app in a **New tab**, or open it **On your phone** from a QR code,
  which joins the same copy of the demo, so what they do on the phone shows on
  the laptop.
- **The rail**: the tour's outline, the scenarios and **Reset the demo**, and
  **Read more**, your [pages](https://getroomi.com/docs/pages) and then your files. **Hide notes**
  gives the stage the whole width; on a phone the notes are closed on arrival,
  and **Show notes** opens them over the stage.
- **Files**: a PDF (a brochure, a deck) or an image, added on the project's
  **Room** tab. A PDF opens in the room's own reader, a page at a time, and
  never leaves the room for another site. The file is sent only to someone
  let into this room, never at an address anyone could pass round.
- **Report this room**, under the stage: a reason and a note, sent to the
  people who look after Roomi, never to you. Anyone in the room can
  send one, signed in or not, a few a day.
- **A notice**, on every room: "This demo runs on mock data. Nothing you do
  here reaches a real system."
- **What happens next?**, at the foot: the viewer's answer to your next step
  ([Brand and next steps](https://getroomi.com/docs/brand)).

Every one of these is recorded as it happens: each app switched to, each frame,
full screen and new tab, the phone, each page and file, each scenario and
whether the demo answered, the tour's steps, the next-steps panel, and where the
viewer left. A PDF's time is kept page by page, so you see which pages were
read and for how long. [Analytics and the pipeline](https://getroomi.com/docs/analytics) shows it to
you.

### Choosing the viewer's controls

**Viewer controls**, on the project's **Room** tab, says which of these the room
offers: the device frame, full screen, a new tab, the phone, driving the story
by hand (the scenarios and the reset), comment mode, reactions, and **What
happens next?**. Every one is on until you choose. One you switch off is gone
from the room at once, for everyone, and the room refuses it if a viewer asks
for it anyway: with no new tab, the demo opens only inside the room or on the
viewer's phone. The tour's own steps still run with the scenarios off.

## Comments

### Leaving one

**Comment** in the room's header turns on comment mode: "Click anywhere on the
app to pin a comment for Northwind." The viewer clicks a spot (**Pin**) or
draws round a part of the screen (**Area**), writes up to 2,000 characters, and
chooses **Send to Northwind**. The pin stays on the stage, marked as sent, and
the mode stays on for the next one until they choose **Exit** or press `Esc`.

A comment is pinned to where it was left: the app, the screen the app was on
(its path, which the demo's page tells the room), and the point on the stage.
An area arrives as its centre.

On a private link, the first comment or reaction asks for an email, once:

> **Your email, once**
> So Northwind knows who this is from. Nothing is ever sent to it, and it is
> not checked.

### Reading and replying

The project's **Feedback** tab lists every comment, newest first: who left it,
on which app and screen, when, what they said, and your latest reply.
**Open** shows one in full:

- **Where**: the app, the screen, and the position, "62% across, 18% down the
  stage";
- **From**: the person, and whether they are the one the link was made for or
  someone it was forwarded to;
- **Conversation**: your replies and theirs, oldest first;
- **Reply**: your answer. "The viewer reads your latest reply in the room, the
  next time they open their link."

**Resolve** marks a comment dealt with; **Reopen** undoes it. Neither changes
anything the viewer sees.

In the room, a viewer with replies has a **Replies** button in the header. It
opens their own comments with your replies, and a box under each to answer
you, which arrives in the comment's conversation in the app. A viewer sees only
their own comments and your answers to them, never anyone else's.

### Screenshots

A comment comes with a picture of the screen the viewer was looking at, with
the pin or area marked on it, and **Open** in the Feedback tab shows it beside
the comment. When the demo's page cannot be pictured, or the viewer took the
picture off before sending, it is the room's outline of the stage instead,
with the pin still where it was left, and a note says why.

## Reactions

A heart, a clap and a fire, in the room's header, each on or off. On a private
link a reaction asks for an email once, as a comment does, and is for you
alone, never other viewers: the project's **Activity** tab lists who put which
on, and when, each person by name, and so do Claude's `insights` and
`viewer_activity` tools. At a public address it needs a sign-in, and is counted publicly on the
community.

## Changing what is live

A deploy makes its build live at once: `roomi deploy --commit` ends by making
the new build live, and so does `deploy_static` with `commit: true`. Everyone
opening a link gets it from their next page load, and nobody's link changes.
A container demo's copies belong to a build, so each viewer's next visit
starts a copy of the new one.

**To roll back**, open the project's **Builds** tab, choose an earlier build and
**Roll back to this** (or **Make this live** for a later one). It asks first:
"Everyone opening a link gets it from their next page load; nobody’s link
changes." From the terminal, `roomi rollback` says which build would go live
and `roomi rollback --commit` makes it so ([CLI](https://getroomi.com/docs/cli#roomi-rollback)).
Through the API, it is `POST /api/projects/:projectId/builds/:buildId/live`.

Pages, next steps, the brand and every link belong to the project, not the
build, so none of them changes when the live build does.

There is no way to take a project's build down and leave it with none. To
close a room for now, pause it ([Pausing a room](#pausing-a-room)); to close
it for good, revoke its links or delete the project.

## The tour on Overview

The project's **Overview** shows the live build's tour step by step: each
step's title, the app it happens in and the calls it makes, and beside each
how its rehearsal went: **Passed**, **Failed**, **Nothing to run**, or **Not
reported**. A step that makes no calls, every step of a static build among
them, is Nothing to run.

`roomi deploy --commit` sends the story's rehearsal with the build it
registers (`registered <id>, with the story's rehearsal (5 steps)`), so each
step that makes calls reads Passed. A rehearsal that failed never publishes,
so Failed is for a build registered some other way. A build whose deploy sent
no rehearsal, such as one made before roomi sent it, reads "Not reported",
never "Passed".

## Pausing a room

To close a room for now without losing anything, pause it. **Pause the
room…** is in the project's Settings, in its Danger zone. It asks first, and
takes an optional note to viewers, up to 280 characters:

> Everyone opening a link to Corner will see a short page saying you paused
> it. No demo starts while it is paused. Resume whenever you like: the same
> links open the room again.

While it is paused, every working link opens a short page instead of the
room:

> **This room is paused.** Corner Studio has paused this room for now. Your link
> still works: the room opens here again when they resume it.

with your note beneath, if you left one. Nothing past that page answers, so no
demo container starts and nothing is recorded as a visit. The links, the
builds and the pages are untouched, and you can still deploy and make links
while it is paused. A link that would not work anyway (revoked, expired,
wrong) shows the same "Not found" it always does, not the paused page.

In the app, a paused project carries a **Paused** chip and a banner. From
Settings you can **Change the note…**, which the paused page shows from then
on, or **Resume the room**, which opens it again on the same links. Every
pause, change of note and resume is kept, with who did it, in **Room history**
on the project's Activity tab; the history cannot be edited.

Through the API it is `pauseRoom`, `resumeRoom` and `getRoomPause`
([HTTP API](https://getroomi.com/docs/api#pausing-a-room)).

### When Roomi pauses a project

A project can also be paused by the platform, never by accident:

- **Over the plan's projects**: when a workspace's plan changes, its most
  recently used projects, up to the plan's allowance, run, and the rest pause.
  They resume when the plan allows them again.
- **Suspended**, or **taken down**, by Roomi.

A project the platform paused admits nobody, on every request, and refuses
new deploys and new links, saying why. Nothing is deleted. A viewer meets the
same "Not found" as a link that does not work, never the paused page, so
nobody learns of a plan or a takedown. The two pauses are separate: resuming
your own never lifts the platform's, and the platform's lifting never reopens
a room you paused. Settings says which applies.

## Revoking and expiry

- **Revoke** a link from the Links tab (it asks: "Revoke Priya Shah's link"),
  with the connector's `revoke_link`, or through the API (`POST
  /api/links/:linkId/revoke`). It stops working at once, on every request, not
  only the next arrival: a viewer still in the room is refused from their next
  request. It cannot be
  undone; make a new link instead.
- **Expiry** works the same way at the moment it passes. An expired link
  cannot be extended; make a new one.

What the link gathered stays: its visits, comments, answers and pipeline card.

## Deleting a project

The project's **Settings** tab has **Delete the project**: type the project's
address to confirm. It leaves your workspace and its links stop working at
once. Its address is held for 30 days before anyone can take it again.

## What a viewer sees when turned away

A room never says why a link does not work, so a refusal says nothing about
what exists. Every one of these is the same plain "Not found":

- the link is revoked, or has expired;
- the project is deleted, or paused by Roomi;
- the workspace is on Free and the link is a private one;
- a listed project's public address after it is unlisted, blocked by a check
  or taken off by Roomi, or while it is hidden from the community;
- the room's own address, opened without a live session;
- an address that was never a link.

A viewer holding a good link can also meet these, each a calm page in the
room's colours:

| When | They see |
|---|---|
| Your workspace has used the month's viewer-hours | "This room is not taking visits right now. Northwind's room has reached its viewing allowance for this month. Your link still works; please get in touch with Northwind directly." |
| A public address already holds five people, or a container demo is at the project's cap | "This demo is full right now. Northwind's demo has as many people in it as it can take at once. Try again in a few minutes." |
| You paused the room | "This room is paused. Northwind has paused this room for now. Your link still works: the room opens here again when they resume it.", with your note |
| Their browser has not said who it is yet | "Are you Priya Shah?" |
| The room requires an email | "Your email, to open this room" |

And, for a container demo, on the stage: "Starting the demo…", "The demo paused
while you were away." with **Resume the demo**, "The demo could not start.",
high demand, or "The live demo is paused right now. The notes are still here."
[Container demos](https://getroomi.com/docs/containers#a-viewers-copy) says when each happens.

## How many at once

- **A private link** on a paid plan has no cap on viewers at once. A static
  demo serves them all from the same files.
- **A container demo** runs one copy per open link, up to the plan's cap for
  the project: 5 on Pro, 10 on Team, 50 on Enterprise. Free runs no
  container demos. A viewer past it is told the demo is full, and counts as
  turned away.
- **A public address** lets five people in at once, whatever the plan, all
  sharing one copy of the demo. A place is held while the viewer's room is
  open, given back when they close the tab, and lapses 45 seconds after their
  room last reported in if the close never arrives.

Each viewer turned away is counted, once per visit per hour, and the app shows
the month's count as **Turned away**. From three in a month it says a paid plan
would have let them in.

## Viewer-hours

Paid plans include viewer-hours a month: time viewers spend in your rooms,
measured from their visits, per calendar month in UTC. Time in a live app
counts twice, and at a public address only time in a live app counts. The app
shows the month's use against the allowance, and warns from 80%:

> You have used 41 of this month’s 50 viewer-hours. At 50, your rooms stop
> taking new visits until 1 November.

At the allowance, no new visit starts, a reload included, no live demo starts
or is kept awake, and new links are refused until the month turns or the plan
changes. Anyone already in a room keeps what is open, a live demo until it
next sleeps. Free has no viewer-hours: its public addresses share 100 hours of
viewing a month instead, and past them new visitors are turned away until the
month turns. [Plans and limits](https://getroomi.com/docs/plans) has each plan's
allowance.

## Free rooms

Free has no private links. A free project is one of two things.

**An unlisted draft.** Only your workspace opens it, with **Preview as
viewer**. Every project starts this way, on every plan.

**Listed on the community.** You write a community card (a title, one line and
a cover) and ask to list it, and Roomi checks the card and the build
there and then. If they pass, the project is public at once at one address, `<project>.getroomi.app`, with the
[community](https://getroomi.com/docs/community) linking to it.

At a public address:

- visitors are anonymous: each is counted, by an id that is hashed and says
  nothing about them;
- five can be in at once, sharing one copy of the demo;
- commenting and reacting need a sign-in with GitHub or Google, in the app,
  which brings them straight back. You see their name, their handle if they
  have one, and their picture, never their email;
- the only next step is a question, sent as a signed-in comment;
- on Free, analytics are total views only, and the workspace's public
  addresses share 100 hours of viewing a month.

Unlisting takes the project off the community and its public address stops
answering at once. Editing a listed card's words or cover, or deploying a new
build, checks it again: it stays listed unless a check fails.

A link made while the workspace was on a paid plan is kept, and shows in the
Links tab as "Closed on Free": it opens nothing on Free, and opens again if the
workspace is on a paid plan again.

> [!NOTE]
> Every workspace starts on Free, and moves to Pro or Team whenever you like, in Settings, Billing. Sign in at app.getroomi.com with GitHub or Google, then add the connector to Claude at https://mcp.getroomi.com/mcp, or run the CLI with npx @getroomi/cli. These pages describe the connector, the CLI, pitch.json, the app and the room as they are.
