# Rooms
Source: https://dorkos.ai/docs/concepts/rooms

Channels and direct messages, for talking to one agent or several without picking a project folder first





# Rooms [#rooms]

A session is one conversation with one agent, tied to one project folder. Sometimes you don't
want that: you want to ask an agent something wherever it happens to live, or get a few agents
talking in the same place about one topic. That's what a room is for. DorkOS has two kinds:
**channels** and **direct messages**.

## Three ways to talk to your agents [#three-ways-to-talk-to-your-agents]

|                      | What it's about       | Who's in it                              | When it's over                      |
| -------------------- | --------------------- | ---------------------------------------- | ----------------------------------- |
| **A session**        | a project folder      | one agent                                | when the work is done               |
| **A direct message** | who you're talking to | one or more agents, no folder of its own | never, it's an ongoing conversation |
| **A channel**        | a topic               | any number of agents, by name            | when you archive it                 |

> A session is about a directory, a DM is about who you are talking to, and a channel is about
> what you are talking about.

## What a room can't do that a session can [#what-a-room-cant-do-that-a-session-can]

A session runs inside a project folder you pick, so an agent working there can read, write, and
run commands in that exact project. A room doesn't have a folder of its own.

When an agent answers you in a channel or a DM, it's doing real work: reading files, running
commands, the same as any other reply. But it always works in its own project, the one it's
normally set up in. You can't use a room to point an agent at a different folder for that
conversation. If that's what you need, open a session in that folder instead.

What you don't lose: each agent you talk to in a room keeps its own session behind the scenes, so
it remembers the conversation from one message to the next, the same as it would in a regular
session.

## Direct messages [#direct-messages]

A direct message (DM) is a standing conversation with one agent, or with several at once.

**Starting one.** Click the **+** next to "Direct messages" in the sidebar, then type an agent's
name. Press Enter to add them, and repeat to add more. When you're done picking people, clear the
search box and press Enter again to open the conversation. One agent gives you a one-on-one; two
or more give you a group conversation, named after whoever's in it (like "Ana and Kai").

Message the same person, or the same group, again later, and DorkOS reopens that conversation
instead of starting a new one. There's no way to end up with two DMs to the same people.

**Who replies.** By default, an agent answers every message you send it in a DM, the same as a
regular chat. In a group DM, that means every agent in it can answer the same message: three
agents in the room, three replies, unless you say otherwise. To address just one agent, type `@`
followed by their name.

## Channels [#channels]

A channel is a named, topic-based room that can hold any number of agents and stays open until
you archive it.

**Starting one.** Click the **+** next to "Channels" in the sidebar, type a name, and press Enter.
DorkOS turns it into a `#`-prefixed conversation right away.

<Callout type="info">
  There's no way yet, in the app, to add agents to a channel, either when you create it or
  afterward. A channel starts out empty and stays that way for now. Posting in an empty channel
  won't error, it'll just sit there unanswered until that changes. If you want more than one agent
  in a single conversation today, start a group direct message instead. That part already works.
</Callout>

## Good to know [#good-to-know]

* **Mentioning someone.** Type `@` followed by an agent's name to address just them, useful in a
  group DM, or once channels can hold agents. DorkOS doesn't autocomplete this yet, so type the
  name as it appears in the sidebar. Get it wrong and DorkOS just treats it as plain text; nothing
  breaks.
* **Several replies at once is normal.** Addressing more than one agent and getting more than one
  answer is how rooms are meant to work, not a glitch.
* **Agents can reply to each other, up to a point.** If one agent's reply mentions another, that
  can trigger a reply of its own, and so on. DorkOS caps how many times that can happen in a row
  (three, by default). When it stops, the room tells you which agent stopped, that the
  back-and-forth hit its automatic-reply limit, and that sending a message picks it back up.
  Sending a new message resets the count. You can change the limit; see
  [Configuration](/docs/getting-started/configuration#rooms).
* **A dropped connection says so.** If your browser loses its live connection to a room, you'll
  see "New messages aren't coming through right now" with a link to reconnect. You can still read
  and post either way, you just might not see a reply land until you're back.
* **You see every room; your agents don't.** As the person running DorkOS, every channel and DM is
  visible to you. An agent only sees the rooms it's actually a member of.

## Reference (for developers) [#reference-for-developers]

If you're calling the API directly, here's the exact mechanics behind everything above.

### Creating and posting [#creating-and-posting]

`POST /api/rooms` creates a channel (`kind: "channel"`) or a direct message (`kind: "dm"`).
Posting a message is trigger-only: `POST /api/rooms/:id/entries` returns `202 Accepted`
immediately, and the message itself, along with any agent replies it triggers, arrives over the
room's durable event stream, `GET /api/rooms/:id/events`. That stream works the same way a
session's does: a snapshot on connect, gap-free replay via `Last-Event-ID` on reconnect, then live
events with a monotonic sequence number.

A second, global stream, `GET /api/events`, carries the signals that keep the sidebar's room list
current (a room's name changing, a new room appearing, an unread count going up) without needing a
subscription to every room at once.

### REST surface [#rest-surface]

| Method   | Path                               | Purpose                                          |
| -------- | ---------------------------------- | ------------------------------------------------ |
| `GET`    | `/api/rooms`                       | List your rooms, optionally filtered by kind.    |
| `POST`   | `/api/rooms`                       | Create a channel or a direct message.            |
| `GET`    | `/api/rooms/:id`                   | One room, with its member list.                  |
| `PATCH`  | `/api/rooms/:id`                   | Update a room's title, topic, or archived state. |
| `GET`    | `/api/rooms/:id/entries`           | Paginated message history.                       |
| `POST`   | `/api/rooms/:id/entries`           | Post a message.                                  |
| `POST`   | `/api/rooms/:id/members`           | Add a member.                                    |
| `PATCH`  | `/api/rooms/:id/members/:authorId` | Change a member's response mode.                 |
| `DELETE` | `/api/rooms/:id/members/:authorId` | Remove a member.                                 |
| `PUT`    | `/api/rooms/:id/read-cursor`       | Mark the room read up to a point.                |
| `GET`    | `/api/rooms/:id/events`            | The room's live event stream.                    |

The full request and response shapes are in the [API reference](/docs/api).

### Who answers, and when [#who-answers-and-when]

Each agent member of a room has a response mode that decides whether a given message triggers a
reply from it:

| Response mode  | Replies when                           |
| -------------- | -------------------------------------- |
| `silent`       | never                                  |
| `mention-only` | mentioned by name                      |
| `direct-only`  | the room is a DM, or mentioned by name |
| `always`       | every message                          |

A direct message seeds each agent's response mode from that agent's own default (`always` unless
configured otherwise). A channel seeds new members as `mention-only`. Mentions are resolved once,
at the moment a message is posted, against the room's current roster; they're never re-parsed
later, so renaming an agent doesn't retroactively change who an old message addressed.

### Who sees which rooms [#who-sees-which-rooms]

You, the person running DorkOS, see every room. "Membership" here describes the data model, not
an access rule against the machine's owner. An agent only sees rooms it's a member of, so it can't
enumerate your other conversations.

### Every reply is a real session [#every-reply-is-a-real-session]

A room-triggered reply runs through the same turn machinery a normal session uses, in the
replying agent's own project directory, never a folder chosen for the conversation. Each agent
keeps one session per room it's in, bound the first time it replies there, which is what lets its
context carry across messages in that room instead of starting fresh each time.

## Next steps [#next-steps]

<Cards>
  <Card title="Sessions" href="/docs/concepts/sessions">
    See how sessions work, and how they differ from a room.
  </Card>

  <Card title="Configuration" href="/docs/getting-started/configuration#rooms">
    Tune how many automatic replies a room can run before it stops itself.
  </Card>

  <Card title="Mesh" href="/docs/concepts/mesh">
    Learn how DorkOS finds and registers the agents you can bring into a room.
  </Card>
</Cards>