Endpoints

A request’s payload begins with one tag byte designating the endpoint; twenty-four 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::fuse_serve
`3`	volumes::list
`4`	volumes::stat
`5`	volumes::read
`6`	volumes::write
`7`	volumes::filetree
`8`	volumes::fuse_serve
`9`	volumes::create_capacity
`10`	volumes::create
`11`	volumes::edit_capacity
`12`	volumes::edit
`13`	volumes::delete
`14`	images::check
`15`	images::list
`16`	images::stat
`17`	images::build
`18`	images::delete
`19`	images::oci
`20`	info
`21`	capacity
`22`	daemons::accept
`23`	daemons::connect

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.
Capabilities. The server states in the capabilities object of its info response which of the parts of this layer it serves, as the Capabilities layer defines, and answers every request past a part it does not serve by the response that layer names for the endpoint. Every requirement of this layer on an endpoint a capability governs holds subject to that layer.

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 obtains the image, deploys, injects the proxy, connects to it and begins it with the arguments, mints the id and has the client register the container — deploy the tools it declared and value the secrets it takes — feeds the values to the container, makes every FUSE mount, 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 obtains the image, deploys, injects the proxy, connects to it and begins it with the arguments, mints the id and has the client register the container — value the secrets it takes — feeds the values to the container, makes every FUSE mount, sends exactly one id, relays the container’s activity, and relays and serves every channel until the run ends.
containers::fuse_serve — Tag 2: a client names a container it is running, by id, and a directory of it; the server opens a FUSE serve of that directory on the proxy of the container, answers Serving once, and for as long as the scope lives relays on channels the client opens the nine asks a FUSE mount makes, each answered from the filesystem of the container, and the tree of the directory as the container holds it; the client stops the scope, or the container ends.
volumes::list — Tag 3: a client asks which volumes are available to it; the server sends every such volume as added, says when the listing is whole, keeps sending as volumes are created, edited and deleted, and finishes when the client stops.
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::read — Tag 5: a client names a volume from its listing and one file in it; the server sends the bytes of the file as responses of at most CHUNK_SIZE bytes each and the finish, or an error last, while the volume is mounted nowhere.
volumes::write — Tag 6: a client names a volume from its listing and one file in it; the server asks for the content on a channel of its own, puts the file in place whole, and answers Written or an error, and the finish, while the volume is mounted nowhere.
volumes::filetree — Tag 7: a client names a volume from its listing and a subtree of it; the server sends exactly one response carrying the tree of that subtree as a snapshot, or an error, and the scope finishes; nothing is watched and no change is sent.
volumes::fuse_serve — Tag 8: a client names a volume from its listing and a cap for an ephemeral layer; the server holds the volume as a mount holds it, answers Serving once, and for as long as the scope lives answers on channels the client opens the nine asks a FUSE mount makes, from the volume as its mode allows, a piece at a time, and streams the tree of the volume as served; the client stops the scope.
volumes::create_capacity — Tag 9: 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::create — Tag 10: a client names a volume, its size in bytes and its mode; 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::edit_capacity — Tag 11: 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.
volumes::edit — Tag 12: a client names a volume from its listing and states a change to it, its size, its mode, or both; the server sends exactly one response stating that the volume has what was stated, that the server has insufficient capacity for the size, that the content of the volume exceeds the size, or an error, and the scope finishes; the size and the mode are the only properties an edit changes.
volumes::delete — Tag 13: 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.
images::check — Tag 14: a client names an image by digest and references and says where the server is to look, among its own images and the registries; the server sends exactly one response stating whether a source asked has the image, that no source was asked, or an error, and the scope finishes.
images::list — Tag 15: a client asks which images it has built on the server; the server sends every such image as added, says when the listing is whole, keeps sending as images are built and deleted, and finishes when the client stops.
images::stat — Tag 16: a client names an image from its listing; the server sends exactly one response carrying the image as the listing reports it and the Containerfile it was built from, or an error, and the scope finishes.
images::build — Tag 17: a client names an image, hands a Containerfile and names a directory of one of its volumes as the context, or none; the server sends the build’s output line by line, then exactly one response stating that the image exists, that the server has insufficient capacity for it, or an error, and the scope finishes; the image persists until the client deletes it.
images::delete — Tag 18: a client names an image from its listing; the server sends exactly one response stating that the image no longer exists, that a running container runs it and it was not deleted, or an error, and the scope finishes; the deletion is not reversible.
images::oci — Tag 19: a client opens a scope to pull what the server holds for it; the server sends nothing on the main stream and, for as long as the scope lives, answers on channels the client opens whether it holds an image for the client and under what name, a manifest by digest, and a blob by digest; the client disconnects, or its connection ends, and the response finish follows.
info — Tag 20: a client asks what a server is; the server sends exactly one response carrying, as JSON, the revision of this specification it implements, 2.3.0, and the capabilities it holds out, and the scope finishes.
capacity — Tag 21: a client asks how much it may still use; the server sends exactly one response carrying, as JSON, four counts of bytes — the room for a new volume, the room in the client image store, the memory and the overlay disk a container run could still reserve — each the most the client could use as of the instant of the response, and the scope finishes.
daemons::accept — Tag 22: a client, the acceptor, offers to take daemon connections under its identity; the server answers the identity once and, for as long as the scope lives, announces each connection a daemon connector opens as a pair of channels, relaying every frame of it unread.
daemons::connect — Tag 23: a client, the daemon connector, names an acceptor by identity and presents its mode; the server announces the connection to the acceptor, answers the byte 0 when the acceptor takes it, and relays every frame both ways, unread, until either side hangs up.