Endpoints

A request’s payload begins with one tag byte designating the endpoint; thirteen endpoints are defined, and a request the server cannot read is answered by a bare response finish.

A request opens a scope for exactly one endpoint. The request’s payload begins with a single tag byte designating the endpoint; the remainder of the payload is the endpoint’s request content, in the form the endpoint defines.

Tag	Endpoint
`0`	containers::agents::run
`1`	containers::tools::run
`2`	containers::tools::connect
`3`	volumes::list
`4`	volumes::stat
`5`	volumes::watch
`6`	volumes::create_capacity
`7`	volumes::create
`8`	volumes::edit_capacity
`9`	volumes::edit
`10`	volumes::delete
`11`	images::check
`12`	version

The tag values are normative as tabulated. Each endpoint has its own section. Every section of this layer states requirements of the server only: a sentence describing what the client sends states the input the server serves, and imposes no requirement on the client.

An unreadable request is answered, not dropped. A request whose payload the server cannot read — a tag the server does not define, or content that does not conform to the endpoint’s form — is answered by a response finish with no response preceding it. The scope opens and closes; the client observes an unanswered request.
Growth is new tag values. A future endpoint is a new tag value in this table. The frame types of the Frames layer are unaffected by the addition of endpoints.

Notation#

The JSON payloads of this layer are defined by type declarations, written as Rust with serde attributes. The declarations are normative for the JSON they describe — the protocol is not Rust, and the notation binds no implementation language — under the following reading:

A struct is a JSON object. A field is a member of the same name, unless #[serde(rename = "…")] states the wire name; r#type is the member type.
A field marked #[serde(default, skip_serializing_if = …)] may be absent, and absence has the marked default’s meaning. An Option field without that marking is present, and may be null.
An enum marked #[serde(untagged)] is exactly one of its variants’ shapes, with no wrapper naming the variant.
An enum of unit variants is a string: each variant’s #[serde(rename = "…")] value, or its name in snake_case where #[serde(rename_all = "snake_case")] is stated. A one-variant enum is thereby a constant.
A field marked #[serde(flatten)] contributes its members to the containing object; the field’s own name never appears.
String is a string; bool is a boolean; u64 and i64 are integers; f64 and Decimal are numbers; Vec<T> is an array; Vec<u8> is an array of integers; a map is an object; serde_json::Value is any JSON value.
Types named from rmcp::model are the types of the Model Context Protocol specification, serialized as MCP defines them; they are incorporated by reference and not restated. Wherever a declaration references one, its definition in rmcp 3.1.2 — the MCP implementation this revision builds against — is linked beneath the declaration.

The binary payloads of this layer that a page marks as postcard are defined by the same type declarations, under the following reading, which is the postcard wire format:

A struct is its fields, in declaration order, with no delimiter between them and no name before them.
u16, u32, u64 and usize are unsigned LEB128 varints: seven bits of the value per byte, least significant first, the high bit of every byte but the last set. A u64 occupies at most 10 bytes. u8 is one byte. bool is one byte, 0 or 1.
String is a varint byte length followed by that many bytes of UTF-8.
Vec<T> is a varint count followed by that many elements, each encoded as T.
An enum is a varint discriminant, the index of the variant in declaration order counted from 0, followed by the variant’s fields in declaration order.
Option<T> is the byte 0, or the byte 1 followed by T.

In this section

containers::agents::run — Tag 0: a client asks the server to run an agent container from an image with limits and mounts; the server holds the content, serves the image, deploys, injects and connects to the proxy, makes every FUSE mount, registers the agent, sends exactly one id, and relays and serves every channel until the run ends.
containers::tools::run — Tag 1: a client asks the server to run a tool container from an image with limits and mounts; the server holds the content, serves the image, deploys, injects and connects to the proxy, makes every FUSE mount, sends exactly one id, and relays and serves every channel until the run ends.
containers::tools::connect — Tag 2: a connector names a running tool container by id and offers an authorization; the server asks the runner, and, when authorized, serves the connector’s channels on the container until the connector disconnects or the run ends.
volumes::list — Tag 3: a client asks which volumes are available to it; the server sends exactly one response carrying every such volume by name, size and age, or an error, and the scope finishes.
volumes::stat — Tag 4: a client names a volume from its listing; the server sends exactly one response carrying the volume as the listing reports it, its bytes in use and the hash of its content, or an error, and the scope finishes.
volumes::create — Tag 7: a client names a volume and its size in bytes; the server sends exactly one response stating that the volume exists, that the server has insufficient capacity for it, or an error, and the scope finishes; the volume persists until the client deletes it.
volumes::watch — Tag 5: a client names a volume from its listing; the server sends the tree of the volume as a snapshot and one response per change to it for as long as the scope lives, or an error; the client ends the watch by one channel request, the stop, and the response finish ends the scope.
volumes::create_capacity — Tag 6: a client asks how large a volume it could create; the server sends exactly one response carrying the largest size, in bytes, of a volume the client could create at that time, or an error, and the scope finishes; the answer reserves nothing.
volumes::edit — Tag 9: a client names a volume from its listing and states its size in bytes; the server sends exactly one response stating that the volume has that size, that the server has insufficient capacity for it, that the content of the volume exceeds it, or an error, and the scope finishes; the size is the only property an edit changes.
images::check — Tag 11: a client names an image by repository and digest; the server sends exactly one response stating whether it can supply that image as the server variant of a container image, and the scope finishes.
volumes::delete — Tag 10: a client names a volume from its listing; the server sends exactly one response stating that the volume no longer exists, that it is mounted and was not deleted, or an error, and the scope finishes; the deletion is not reversible.
volumes::edit_capacity — Tag 8: a client names a volume from its listing; the server sends exactly one response carrying the number of bytes by which the size of that volume could be increased at that time, or an error, and the scope finishes; the answer reserves nothing.
version — Tag 12: a client asks which revision of this specification a server implements; the server sends exactly one response carrying the string 2.3.0, and the scope finishes.