Molerat Protocol Specification

Molerat Protocol Specification

1 molerat v0.1.0-alpha

Molerat is yet another protocol like Gemini or http/html/css. It features extended functionality over Gemini while keeping a low bar-of-entry.

1.0.1 The Name

In nature, naked mole-rats are unusually resistant to cancer. This reflects the philosophy of Molerat- to provide a useable platform, resistant to feature creep.

Not only are naked mole-rats highly resistant to cancer, but they also have unusually long life-spans for rodents. This is interpreted as a good omen for the Molerat project- may it live a long and cancer-free life.

1.0.2 Inspiration

Molerat is heavily inspired by http and Gemini choosing to adopt many principles from both. A core philosophy for Molerat is don’t do it differently just because someone else is already doing it. This is also known as steal good features.

1.0.3 Mascot

Molerat is represented by Potat the naked mole-rat.

Potat, the naked mole-rat.

1.1 Overview

molerat adopts the TOFU TLS TOFU TLS stands for trust on first use transport layer security. It is a system of securing against MITM (man in the middle) attacks where a malicious actor impersonates the server in order to serve altered content.

standard from Gemini. TOFU works by storing an id or key for a specific server. On future connections, the client will check to make sure the key still matches the original. If it does not it will produce an error and alert the user as the client may be connected to an impersonator instead.

For data transfer, Molerat uses request and response headers to define different types of operations like getting, or putting data.

For markup, Molerat uses a markdown-like syntax to define page content like links, text formats, and user-interaction.

1.2 Molerat URI Scheme

Molerat mostly conforms to the base URI syntax defined in RFC 3986. Similar to Gemini, Molerat does not use the userinfo component of URIs.

Molerat URIs use the scheme “molerat” and a default port of 2693.

1.3 Requests

Basic Molerat requests are built using the format

<kind> <url>


  • kind corresponds to the type of request being made.
  • url corresponds to the URL of the content being requested.
  • crlf corresponds to a carriage-return line-feed, or \r\n.

Molerat supports three different request types. Those are;

  • get
  • put
  • del

1.3.1 Get

In Molerat, get is used to request content from a server. The server need only respond with the content, no other action is necessary.

Here is an example get request for the content at molerat://


To get the content at molerat://


To get the content at molerat://


Note that every request must end with a double crlf. They are not visible when rendered on this page, however to a standard Molerat request in bash one would have to include them like this:

echo 'get\r\n\r\n'

1.3.2 Put

put is used to send content to a server. What is done with that content is up to the server, but it is generally expected to update a record, or create a new one with the data provided. The server may then respond with a new page for the client to display.

put also includes the data being sent as a list of <key>:<value> records. These records are delimited by a <tab><crlf> and are formatted as <key>:<value>. A <tab><crlf> following the final key is optional.

Here is an example of a put request to submit a username/password for a login page:



As you can see, there are two separate sections to a form. These sections are delimited with a \r\n\r\n and they give the server information about the form being submitted. For more information on these header keys, see Section 3.4

Multi line form values are also allowed as long as they do not contain a tab directly followed by a crlf:


story:Once upon a time...
There was a beautiful naked mole-rat named Potat. Potat loved things such as marshmallows and stargazing, he found every part of his life to be enjoyable.

Keys must not be empty. For example, this would be an invalid put request:



Servers implementing the Molerat protocol should reject put requests with empty keys.

Note that keys can, however, be solely whitespace. This counts as not being an empty key.

Here is a valid put request printed in bash:

echo 'put\r\nlength:64\t\r\nhash:336ef7e928bfa7de38f84917a976728daca6e67160e6aac7b9fa6ec16784151d\r\n\r\nusername:potat\t\r\npassword:molerat'

1.3.3 Del

del is used to delete a resource. It is syntactically the same as a get request. A del request can be used to clear up the put request. Since otherwise it would have to be used to request deletion of a resource in a server.

Here is an example of a del request:


del can use the same form headers and content as put, so it is possible to send authentication via login/password with a del request.

1.3.4 All three

Here is an example of a typical user session on a theoretical social media site using Molerat requests:

  1. get other user’s posts:
  1. put a post:
content:Hi! I'm the new mascot for the Molerat protocol!
  1. del an older post:
  1. View other posts:

1.4 Responses

Molerat formats responses as



  • status corresponds to the status code of the request. See below for more information on available status codes.
  • message is an optional message from the server to the client. It can be used to send error messages or context-specific messages.
  • type corresponds to the MIME Type of the data being sent. The recognized list of MIME types is available at A valid MIME definition is defined in RFC 2046.

  • length is the decimal byte-length of of the content being sent.
  • hash is a unique identifier for that page. It is suggested to be a sha256 hash. But the only requirement is that it be 1024 or fewer bytes.
  • content is the raw data for the client to display.

In a response containing no content, length and hash should not be included. Additionally, the type component should not be included.

Molerat responses are really just key-values with an optional content section at the endNote that the exception to this is the status field. Status is just the first line of the response indicating the server and response status.

. Here is another way to write the template above:



Here is an example valid call and response for a get request:





Hello, from Potat.

Or, using escape codes:

# Request
echo 'get\r\n\r\n'

# Response
echo '10\r\nmessage:Success\t\r\ntype:text/plain\t\r\nlength:18\t\r\nhash:c28de73edf48cbc93eafb11f7266fc2268b9c7c77f9df02e74e0561e6cea7595\r\n\r\n'

Note that as with put requests, the final form delimiter <tab><crlf> is not necessary in a response.

Molerat mandates a hash key to allow clients to optionally cache pages. It should not be used to reliably validate them, however. Instead, a client may read the hash key before allocating memory to load the content, and if it finds an identical one in it’s store, it may display that page instead. This can be used to ease-up on network strain for long documents, as Molerat does not support compression during transport.

Clients are not required to keep a hash cache, and if they do, user options to control the hash should be available.

1.5 Status Codes

Molerat specifies several types of responses status codes:

  • 1x codes are used for success messages.
  • 2x codes indicate redirection.
  • 3x codes indicate client errors.
  • 4x codes indicate server errors.
  • 5x codes are used for TLS signatures.

1.5.1 1x Codes

1x codes are success messages. They indicate that the client request has succeeded. 10

Success. Everything went OK and the new page is attached. 11

Content unchanged. The request was a success, but the client should not update the page.

1.5.2 2x Codes

2x codes indicate redirection. The server may tell the client see another resource. The redirect location should be an encoded URL in the message component of the response. The server may optionally include content to be displayed while the redirection is taking place. 20

Permanent redirect. The client should not make further requests to this resource. 21

Temporary redirect. The client should temporarily see another source, but not cache the redirect.

1.5.3 3x Codes

3x codes are for client errors. These should be sent as a response using the message component to explain the error. Servers may optionally include content to display a richer error to the user. Otherwise, the client should display a generated error page. 30

Malformed request. Due to an error with the client, the server was unable to parse the request being sent. 31

Invalid request. The server was able to parse the request, but the data included is not valid in this context. This code should be used for authentication failures and put requests containing data that the server cannot accept. 32

Not available. The requested resource does not exist or is not available to the client. This code can be used for both nonexistent resources, and for cases where the client does not have access to the resource.

1.5.4 4x Codes

4x codes indicate an unrecoverable failure on the server. If possible, the server should catch internal errors and respond with a 4x code. 40

Internal error. The server cannot proceed as it has encountered an error it does not know how to handle. 41

Not supported. The server does not support or allow access to this resource by the client. 42

Slow down. The client is being rate limited. The message component should be a number corresponding to the seconds a client must wait before making another request to the server.

1.5.5 5x Codes

5x codes are used for when the server requires a client key to access a resource. 50

Client certificate required. The server requires that the client provides a certificate to proceed. The client should retry the request using a certificate.

1.6 MIME Types

In responses, the server may specify any valid MIME type. It is up to the client to determine how best to display or open the file. Molerat also supports parameters for MIME types like charset. As with Gemini, the default charset is UTF-8 for text content.

1.7 TLS

Molerat chooses to adopt many standards from Gemini for TLS. As with Gemini, use of TLS for Molerat requests and responses is required. Additionally, as with Gemini, use of the Server Name Indication extension is TLS is also required. This allows multiple domains to be hosted on a single server while remaining secure.

Molerat expects that clients and servers use TLS version 1.2 or higher.

1.7.1 Client

Clients may use certificate to identify themselves to a server, but a Molerat client should not use a certificate by default.

If a resource requires a certificate (via the 50 status code) then the client should allow the user to specify whether to use a short-lived certificate, or a long-lived one.

1.7.2 Validation

Molerat recommends the same methods of server certificate validation as Gemini (TOFU). Clients may validate server certificates however they want, including not at allNo matter how a client validates a server certificate, it should always strive to be transparent with the user on how it does so.


Molerat is a simple protocol, so the need for CA certificates is overly-complex. Of course, a client and server may implement it, but clients should . Of course, a client and server may implement it, but clients should accept self-signed keys by default.

1.8 Molerat Text (mtxt)

Molerat text, or mtxtis the format that Molerat uses to present pre formatted text.

mtxt supports several features, but not all of them must be implemented by every client. A server serving mtxt should use a MIME Type of text/molerat. Like Gemini, Molerat supports an optional lang parameter in addition to charset. Clients may use this for any purpose such as displaying text in the correct direction, or auto-translating to a different language. As with Gemini, the lang parameter accepts comma separated language tags from the IANA Language Registry

type:text/molerat; lang=en

Specifies a mtxt document that is in English.

1.8.1 Headings

Molerat supports three levels of heading denoted by a hashtag (#) and then a space. The number of #s denotes the level of heading.

# Title Heading

## Subtitle Heading

### Sub-Subtitle Heading

Rendered in HTML, it would look like this:

Title Heading

Subtitle Heading

Sub-Subtitle Heading

1.8.2 Text

Regular text is simply written on a standalone line. Line breaks are ignored unless there are two in a row. mtxt should not be manually line-wrapped when written, clients should instead choose how and where to wrap text.

This is a regular paragraph. The client will choose when to break the line, to better accommodate the user and their device.

This line has a break,
but it will not show up when rendered since it is only one break. 
People can use a single line break to make it easier to write
mtxt without changing the end-result.

This line has a manual break,

This line will show up on a new line after the previous.

People can use this to separate paragraphs, and other distinguished content.

This is how the previous text should look:

This is a regular paragraph. The client will choose when to break the line, to better accommodate the user and their device.

This line has a break, but it will not show up when rendered since it is only one break. People can use a single line break to make it easier to write mtxt without changing the end-result.

This line has a manual break,

This line will show up on a new line after the previous.

People can use this to separate paragraphs, and other distinguished content.

1.8.3 Subtext formatting

Like Markdown, asterisks (*) can be used to format text inside a paragraph.

*This text is italic*

**This text is bold**

***This text is italic and bold***

This text is italic

This text is bold

This text is italic and bold

Text surrounded by a single asterisk will be italic, double asterisks will be bold, and triple asterisks should be italic and bold. Asterisks should not style text if surrounded by whitespace.

This word is italic: *Potat*

This word is NOT italic: *Potat *

Neither is this one: * Potat*

And DEFINITELY not this one: * Potat *

This word is italic: Potat

This word is NOT italic: *Potat *

Neither is this one: * Potat*

And DEFINITELY not this one: * Potat *

Asterisks can be escaped with a backslash (\) character.

*I should be italic, but I'm not\*

\*I have fallen to the same predicament*

\*I have too...\*

*I should be italic, but I’m not*

*I have fallen to the same predicament*

*I have too…*

Inline links can be specified via the [[ and ]] Characters. Links can link to any type of content like mtxt, images, audio, videos, and even to other pages on other protocols.

The following is a link to another Molerat page:

[[This links to!]molerat://]

It would be displayed like this:

This links to!

A link in mtxt consists of three parts:

  • The display text.
  • The URL.
  • The media type. Display Text

In a link, the text at the very center of the double braces ([[ and ]]) is the text that the client should display to the user. If no text is specified, then the client should display the URL. The URL

The URL is a link to the resource that the client should fetch. It is located on the right-hand side of the double braces. If there is no protocol (or scheme) specified (like http://, gemini://, or molerat://), then the client should treat the URL as a relative link on the same website. i.e. if a URL is /about, and the user is on molerat://, then the client should interpret the URL as molerat:// The Media Type

The media type goes on the left-hand side of the double braces and specifies the type of data that is being linked to. By default, it is mtxt, so it can be left blank for regular links to other webpages.

If the link is to a media-type that is uncommon, or widely unsupported by the client, then the media type may be a MIME type.

Molerat also supports several shorthand media types.

  • ! - Denotes an image of types image/png or image/jpeg.
  • . - Denotes a video of type video/mp4.
  • " - Denotes an audio clip of types audio/mp4, audio/mp3, or audio/wav.
  • # - Is for auto. The client should guess how to display the content to the best of it’s abilities. Clients are not required to do anything for auto Media types, but they should offer the ability to open or download the linked media.
  • - - Can be used to force the client to treat the link as a text link.

Here are some examples:

[[see here for more info]molerat://]

Links to molerat:// and has the text “see here for more info”. It looks like this:

see here for more info


Links to molerat:// without any text. It looks like this:


[![A naked mole-rat.]]

If the client supports it, this will embed an image into the text content. Otherwise it will appear as a linkClients without image support should provide some visual way to distinguish regular links and images.

. Images with display text should use it as an alt text for screen readers.

It should look like this: