River
Ctrl K
Open River

Foundations

How River Fits Together

The fastest way to understand River is to follow one loop, end to end. Once you see how the layers stack up, the rest of the product makes sense.

The six layers, at a glance#

Senses        →  how the world gets in
Home          →  where everything lives
Nervous System →  what happens, recorded in real time
Intelligence  →  who acts on what's happening
Surface       →  what you see and use
Boundary      →  who can see and collaborate

Each layer is a real thing in River — a set of product surfaces and concepts you can point to. Together they form a runtime that keeps running whether you're paying attention or not.

Trace one email, top to bottom#

The simplest way to feel the layers is to watch a single email move through them.

1. Senses — an email arrives#

You connected Gmail to River when you signed up. A new email lands in your inbox. The Gmail integration sees it and ingests it.

This is the Senses layer doing its job: turning external stimulus into internal substrate.

2. Home — it becomes an entity#

Within seconds, the email is now an Email entity in your Dataspace. It has a permanent path in the entity tree, full text indexed for search, attendees linked to your Contacts, and metadata you can query.

Closing your tab doesn't lose it. Switching devices doesn't lose it. The entity is the Home layer doing its job: giving every piece of work a permanent address.

3. Nervous System — an event fires#

The instant the entity is created, an email.received event fires on your Dataspace's Event Stream. It's recorded with a timestamp, the actor (the integration), and a reference to the new entity.

The Nervous System doesn't decide what to do with the event. It just guarantees that the event happened, durably, and that anything subscribed to that event type can hear it.

4. Intelligence — an Agent wakes up#

You built an Inbox Triage Agent last week. It's subscribed to email.received for emails matching specific criteria (your investors, your customers, anything urgent). The event matches its trigger.

The Agent wakes up, reads the email, classifies it, drafts a reply if needed, and writes the result back as another entity — all as a Job with a full execution record.

This is the Intelligence layer in action: persistent workers that wake up on events, do the work, and write the result back into the world model.

5. Surface — you see it#

Two things change on your Surface:

  • A notification surfaces in your inbox: "Inbox Triage drafted a reply to Maya."
  • The draft appears as a Window the next time you open Mail.

You didn't have to ask. The work was done by the time you turned to it.

6. Boundary — your team sees it (or doesn't)#

Because this happened in your team Dataspace, your assistant can see the same draft. They review it, finalize the wording, hit send.

Or — if it had happened in your personal Dataspace, none of this would be visible to anyone else.

That's the Boundary layer: not where work happens, but where it's allowed to be seen.

What just happened#

A single external stimulus moved through six layers and produced finished work, with audit trails, multiplayer collaboration, and proper privacy boundaries — all without you actively doing anything in the moment.

That's the loop. That's what makes River feel like an OS.

The five-minute version#

If you only have five minutes:

  1. Everything in River is an entity, with a permanent home.
  2. Things flow in through Senses and become entities.
  3. Every action — yours or AI's — fires an event on the Event Stream.
  4. Agents subscribe to events and do work without being asked.
  5. Their output is more entities, visible to you on the Surface.
  6. Dataspaces decide who can see all of it.

That's the whole product, in one paragraph.

Where to go next#