Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Model client identity on host attachments (#11214)

Trevor Manz705115cb758e
diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.py
index c895da9ab8..82c63454ae 100644
--- a/marimo/_core/protocol.py
+++ b/marimo/_core/protocol.py
@@ -549,20 +549,32 @@ class Attachment(Struct, frozen=True):
kind: Annotated[
str,
Meta(
- description="What kind of thing is attached, such as `browser`, `editor`, or `agent`. Clients accept kinds they do not recognize."
+ description="What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize."
),
]
name: (
Annotated[
str,
Meta(
- description="A label to show people, such as the browser or editor's name. Null when there is none."
+ description="A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty."
),
]
| None
)
notebook_id: NotebookId
since: Annotated[datetime, Meta(description="When it attached.")]
+ identity: (
+ Annotated[
+ str,
+ Meta(
+ description="The opaque client identity supplied by `Marimo-Attachment-Identity`.\nOmitted when none was supplied. Consumers can group attachments\nwith the same identity within a host. It does not identify an\nindividual connection or change its lifetime.\n",
+ max_length=128,
+ min_length=1,
+ pattern="^[!-~]+$",
+ ),
+ ]
+ | UnsetType
+ ) = UNSET
class AttachmentMessage(Struct, frozen=True):
diff --git a/protocols/host/fixtures/attachments.sse b/protocols/host/fixtures/attachments.sse
new file mode 100644
index 0000000000..48da9a0ca8
--- /dev/null
+++ b/protocols/host/fixtures/attachments.sse
@@ -0,0 +1,18 @@
+event: attachment
+data: {"attachment":{"id":"a1","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:00Z"}}
+
+event: attachment
+data: {"attachment":{"id":"a2","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:01Z"}}
+
+id: 100
+event: ready
+data: {}
+
+id: 101
+event: attachment.removed
+data: {"id":"a1","time":"2026-10-01T09:20:02Z"}
+
+id: 102
+event: attachment
+data: {"attachment":{"id":"a3","notebook_id":"n1","identity":"agent-123","kind":"agent","name":"Notebook CLI","since":"2026-10-01T09:20:03Z"},"time":"2026-10-01T09:20:03Z"}
+
diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yaml
index 5d9ffdc0e9..b12a55c3eb 100644
--- a/protocols/host/openapi.yaml
+++ b/protocols/host/openapi.yaml
@@ -190,8 +190,13 @@ paths:
Opening this stream attaches the client to the notebook. An
attachment appears on both streams while the connection is open
- and is removed when it closes. The snapshot includes every run
- that is not yet completed, with its executions and items, plus
+ and is removed when it closes. Every opening, including a reconnect,
+ creates a separate attachment. The optional
+ `Marimo-Attachment-Identity` header supplies its `identity` so
+ consumers can group connections from the same client. A shared
+ identity does not merge attachments or extend their lifetimes.
+ The snapshot includes every run that is not yet completed, with
+ its executions and items, plus
any completed results the host retains. Result retention is
independent of replay history. Removed objects are absent from
snapshots; a resumable stream carries their removal events.
@@ -209,6 +214,9 @@ paths:
- $ref: '#/components/parameters/Types'
- $ref: '#/components/parameters/RunFilter'
- $ref: '#/components/parameters/LastEventId'
+ - $ref: '#/components/parameters/AttachmentIdentity'
+ - $ref: '#/components/parameters/AttachmentKind'
+ - $ref: '#/components/parameters/AttachmentName'
responses:
'200':
description: The notebook, then changes, as server-sent events.
@@ -562,6 +570,46 @@ components:
own loopback interface, and clients never follow redirects, so the
token never leaves the machine.
parameters:
+ AttachmentIdentity:
+ name: Marimo-Attachment-Identity
+ in: header
+ required: false
+ description: |
+ An opaque client identity, copied to the attachment's `identity`.
+ Clients can reuse it across streams and reconnects so consumers
+ can group their attachments within a host. It is descriptive data,
+ not an authentication credential or an idempotency key. Every
+ stream still creates its own attachment. Invalid values receive
+ a 400 `invalid-request` response.
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 128
+ pattern: '^[!-~]+$'
+ AttachmentKind:
+ name: Marimo-Attachment-Kind
+ in: header
+ required: false
+ description: |
+ What kind of client is attached, such as `browser`, `editor`, or
+ `agent`. Copied to the attachment's `kind`; omitted means `client`.
+ Hosts accept kinds they do not recognize. Values must contain one
+ or more lowercase ASCII letters, digits, or hyphens; invalid values
+ receive a 400 `invalid-request` response.
+ schema:
+ type: string
+ pattern: '^[a-z0-9-]+$'
+ default: client
+ AttachmentName:
+ name: Marimo-Attachment-Name
+ in: header
+ required: false
+ description: |
+ A human-readable label copied to the attachment's `name`, such as
+ `Notebook CLI`. Omitted or empty means the attachment's name is
+ null. The value must be at most 256 bytes when encoded as UTF-8;
+ longer values receive a 400 `invalid-request` response.
+ schema: { type: string }
IdempotencyKey:
name: Idempotency-Key
in: header
@@ -856,17 +904,28 @@ components:
An attachment is a consumer connected to a notebook, such as a
browser tab, an editor, or an agent. Opening the notebook's stream
creates one. It is removed when that connection closes, and not
- when the notebook's runtime stops or restarts.
+ when the notebook's runtime stops or restarts. Each stream has its
+ own attachment, even when several share a client identity.
required: [id, notebook_id, kind, name, since]
properties:
id: { $ref: '#/components/schemas/AttachmentId' }
notebook_id: { $ref: '#/components/schemas/NotebookId' }
+ identity:
+ type: string
+ minLength: 1
+ maxLength: 128
+ pattern: '^[!-~]+$'
+ description: |
+ The opaque client identity supplied by `Marimo-Attachment-Identity`.
+ Omitted when none was supplied. Consumers can group attachments
+ with the same identity within a host. It does not identify an
+ individual connection or change its lifetime.
kind:
type: string
- description: What kind of thing is attached, such as `browser`, `editor`, or `agent`. Clients accept kinds they do not recognize.
+ description: What kind of thing is attached, supplied by `Marimo-Attachment-Kind`, such as `browser`, `editor`, or `agent`. Defaults to `client` when the header is omitted. Clients accept kinds they do not recognize.
name:
type: [string, 'null']
- description: A label to show people, such as the browser or editor's name. Null when there is none.
+ description: A label to show people, supplied by `Marimo-Attachment-Name`, such as the browser or editor's name. Null when the header is omitted or empty.
since:
type: string
format: date-time
diff --git a/protocols/host/spec.md b/protocols/host/spec.md
index 03b98c6c82..2281e50c35 100644
--- a/protocols/host/spec.md
+++ b/protocols/host/spec.md
@@ -97,9 +97,19 @@ choosing how it is stored and which operations each client can use. Several
clients can share a notebook while only some are permitted to edit or save it.
An **attachment** represents a client's connection to a notebook. It belongs to
-the notebook and remains connected across runtime restarts. Stopping a runtime
-ends its active work and loses its Python state, while the document and retained
-results remain available to clients.
+the notebook and remains connected across runtime restarts. Each opening of a
+notebook's event stream MUST create a separate attachment, removed when that
+connection closes, including when reconnecting with `Last-Event-ID`.
+
+When opening a stream, clients MAY supply `Marimo-Attachment-Identity`,
+`Marimo-Attachment-Kind`, and `Marimo-Attachment-Name`. Hosts expose these as
+`identity`, `kind`, and `name` on the attachment, as defined in the OpenAPI
+schema. Consumers can use a shared identity to group attachments from the same
+client across streams and reconnects. Each attachment still has its own id and
+lifetime; identity does not merge connections or keep an attachment alive.
+
+Stopping a runtime ends its active work and loses its Python state, while the
+document and retained results remain available to clients.
### Runs and results