What is Gemini?

Gemini is both a document markup format and an internet protocol for accessing and downloading documents and other files.

The official project website is gemini.circumlunar.space.

Document format

The Gemini format is a plain-text format. The formatting is line-based and the documents are encoded using UTF-8.

Since the document format is simple and lacks recursive feautures, it can be parsed with a basic state-machine parser.

Network protocol

The Gemini protocol is a simple network protocol that can be used to fetch files from servers. The protocol follows a request-response model, and handles one response per connection. This is similar to HTTP with the Connection: close header.

The protocol uses a TLS connection over TCP. Here’s how a simple exchange looks.

  1. Client establishes connection to the server.
  2. Client sends the requested URL, followed by a newline. gemini://example.com/homepage.
  3. The server responds with a status code and a MIME type, followed by a newline.
  4. Any content received until the connection closes is the response body.


The project was well-received in Hacker circles; such as Hacker News, the Tildeverse and the Fediverse. A lot of people who are involved with the Gopher protocol have shown interest in the Gemini protocol as well.

Simplicity, or lack thereof

Most aspects of the protocol and the document format are very simple and easy to implement. Despite this, the protocol specification mandates the use of TLS, making stand-alone implementations very difficult. If one is okay with using an external library or wrapper to implement TLS, the rest of the protocol should be quite simple.


As Gemini has been designed with implementation simplicity in mind, there is a large number of Client and Server implementations available.

Client implementations

// TODO: Fill section

Server implementations

// TODO: Fill section

Relevant links