{"canonical_url":"https://engineer.company/glossary/gemini/","content_markdown":"# Gemini\n\n## What it is\n\nGemini is an application protocol for fetching documents in which the whole exchange is one\nencrypted connection, one address sent by the client, one response sent back and the connection\nclosed. Its own documents call it the Gemini protocol; its addresses begin with `gemini://`, a site\nserved over it is a capsule, and the network of such sites is Geminispace.\n\nThe project started in June 2019 under its founder, Solderpunk, who remains its “Benevolent\nDictator”. Its specification, version 0.24.1, is dedicated to the public domain under CC0 and\ndescribes the protocol as “an incremental improvement over Gopher [RFC1436] rather than a stripped\ndown HTTP”. The project's FAQ makes the comparison from the other side: the protocol “looks kind of\nlike something between HTTP 0.9 and HTTP 1.0”, with a single kind of request, roughly a `GET`.\n\nA client connects to TCP port 1965, a number that marks the first crewed Gemini mission, flown in\nMarch 1965, and completes a TLS handshake; both sides must support TLS 1.2 or higher. It sends the\nabsolute URL followed by a carriage return and a line feed, and that URL may be at most 1,024 bytes\nlong. The server answers with a single header line: a two-digit status code, a space and a short\npiece of text whose meaning depends on the code. The codes fall into six groups: 10–19 ask for\ninput, 20–29 mean success, 30–39 redirect, 40–49 are temporary failures, 50–59 are permanent ones\nand 60–69 concern client certificates. On success the text is a MIME type and the body follows as\nraw bytes, with no compression and no chunking. The server then closes the connection with TLS's\nclose_notify message, which is how the client knows it has everything.\n\nIt can carry any kind of file, though it was designed alongside a document format of its own,\ngemtext, served as `text/gemini`.\n\n## Why it matters\n\nThe real decision is rarely whether to move a site to Gemini. The FAQ says the protocol is not\nintended to replace the web or Gopher, and it has a name for publishing the same content on two or\nthree of them: bihosting or trihosting. The owner's question is whether a second front door is worth\nkeeping open.\n\nWhat it offers is privacy by construction. The FAQ states that Gemini “does not and never will\ncontain an equivalent of the Cookie, Referer or User-Agent headers”. A request is a URL and nothing\nelse, so a server has very little to record even if its operator wanted to, and there is no script\nin the reader's client to report back. The FAQ names “defensive non-extensibility” among the\npriorities behind the design: the request and response formats have no room for a new header field,\nso a later version has no place to bring tracking back in. For a publisher of plain text, that is\nthe whole appeal.\n\nWhat it costs is much of what the web has grown since HTTP 1.0. There are no cookies, so a capsule\nthat has to recognise a returning reader asks for a client certificate instead, and the reader has\nto create and keep one. There is no certificate authority by default: the specification strongly\nrecommends Trust on First Use, or TOFU, in which a client accepts whatever certificate a server\npresents the first time and pins it afterwards, which turns the server's certificate into a\nlong-lived promise. Encryption hides the page but the server's name travels in TLS's Server Name\nIndication, and the FAQ admits that the hostname “is currently still leaked”. Readers need a\ndedicated Gemini client rather than a browser, so the audience is small. And large files are a poor\nfit, because a response carries neither a size nor a checksum.\n\nA team that needs interactive forms, accounts with passwords, analytics or rich layout\nbelongs on the web. A team that publishes documents and wants a channel without cookies\nor client-side scripts can add Gemini at little cost, as long as the content already\nexists as files.\n\n## What it looks like in practice\n\nengineer.company is itself a capsule, at `gemini://engineer.company`. The [Credits](/credits/) page\nnames Agate as the program that answers Gemini requests, beside Caddy for the web, Gophernicus for\nGopher and Tor for the onion service. All four read the same folder of files, so one deploy updates\nall four and none of them can drift from the others. That is the FAQ's bihosting carried to four\nchannels, done in the cheapest way there is: the capsule is one more reader of a folder every deploy\nalready fills, not a second site to keep in step.\n\nThe same page is frank about the limit described above. It says that Gemini and Gopher each want\ntheir own client rather than a browser, and that Gopher carries which page you read in the clear.\nGemini encrypts that, but the network you read from still sees which address you asked for. That is\nthe server-name leak from the FAQ, described from the reader's chair rather than the designer's.\n\nThe [Privacy](/privacy/) page distinguishes application access logs from operating-system logs.\nThe Gemini and Gopher applications keep no access log; since September 2026, their daily counters\nrecord only aggregate request totals. Gopher also has an operating-system connection log\ncontaining the source address; that log expires after 30 days.\n\n## Where it goes wrong\n\nMost Gemini trouble shows on the first line of a response, and that line is easy to read by hand\nwith nothing but OpenSSL:\n\n```sh\nprintf 'gemini://engineer.company/\\r\\n' |\n  openssl s_client -quiet -connect engineer.company:1965 \\\n    -servername engineer.company\n```\n\nThe first line that comes back is the header, `20 text/gemini;lang=en` for this capsule, and the\npage follows it.\n\n**Returning readers are warned that the capsule may be under attack.** Clients that follow the\nspecification save the fingerprint and expiry date of the first certificate they see. A different\ncertificate before that date has passed counts as “potential evidence of a Man-In-The-Middle\nattack”. An operator who generates a fresh certificate on every deploy, or moves the capsule to a\nnew machine without its key, sets off that warning for every regular reader. Back up the key and\ncertificate with the rest of the server, issue the certificate for a long period, and replace it\nonly after the expiry date that clients already have on file.\n\n**A search box answers with status 59.** A status 10 response asks the reader for a line of input,\nand the client sends it back as the query part of the same URL, percent-encoded. The URL is capped\nat 1,024 bytes, and a server must reject anything longer as a bad request. A long answer fills that\nquickly, and text outside ASCII fills it faster: a Cyrillic letter is two bytes of UTF-8 and six\nonce encoded. Ask for short answers, and use status 11 for sensitive input such as a passphrase, so\nthat clients do not echo it to the screen.\n\n**Readers are signed out between pages.** The protocol has no cookies, so session state kept the web\nway does not survive from one request to the next. A capsule that needs to know who is asking\nreturns status 60, the reader's client creates a certificate, and the server recognises it on later\nrequests. The specification limits that certificate to the host and port that asked for it and to\nthe requested path plus everything below it, so put every page that needs the identity under one\npath. Say on the page what the certificate is for, because the reader has to agree to it.\n\n**A large download arrives cut short and nobody notices.** A response carries no length and no\nchecksum, so a transfer that stops halfway can look much like one that finished, apart from the\nmissing close_notify. The best-practices guide suggests that files larger than 100MiB are best\nserved some other way. Put large files on HTTPS and link to them from the capsule; a Gemini page may\nlink to any URL scheme.\n\n## Further reading\n\n- [Gemini network protocol specification](https://geminiprotocol.net/docs/protocol-specification.gmi)\n  — requests, every status code, the use of TLS and certificate pinning, in one short document.\n- [Project Gemini FAQ](https://geminiprotocol.net/docs/faq.gmi) — the project's aims, its comparison\n  with HTTP and Gopher, and its own answer to the charge that TOFU is weak.\n- [Best practices for Gemini implementations](https://geminiprotocol.net/docs/best-practices.gmi)\n  — file naming, large files, redirect limits and TLS settings.\n- [History of Project Gemini](https://geminiprotocol.net/history/) — how a 2019 idea from\n  Gopherspace grew into a network of its own, told by the project.\n\n\u003chttps://engineer.company/glossary/gemini/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What the Gemini protocol is, why a site would serve its pages over it as well, and the trust, privacy and file-size limits that catch new operators out.","formats":{"gemtext":"https://engineer.company/glossary/gemini/index.gmi","gopher":"https://engineer.company/glossary/gemini/gophermap","html":"https://engineer.company/glossary/gemini/","json":"https://engineer.company/glossary/gemini/index.json","markdown":"https://engineer.company/glossary/gemini/index.md","pdf":"https://engineer.company/glossary/gemini/index.pdf"},"kind":"page","language":"en","title":"What is Gemini?","url":"https://engineer.company/glossary/gemini/","version":1}