DEV Community: minerobber

How I made a barebones Gemini client for the Mini Micro

minerobber — Fri, 23 Oct 2026 19:35:03 +0000

I recently read Joe Strout's article on a multiplayer network starter for Mini Micro, and it reminded me of a project I finished up last month, so I figured I'd write that project up, in a similar style to my last dev.to article on porting MiniScript to Cosmopolitan Libc.

Part the First: "What does the title mean?"

To make the couple paragraphs I spent on MiniScript in my last article into one shorter one, MiniScript was invented by Joe Strout in 2016 and released in 2017 as a new beginner language for teaching kids how to code. MiniScript's language reference fits on one side of a sheet of US Letter paper and the reference for Mini Micro, the "killer app" of MiniScript so to speak, only takes 3 more pages (the last page of that PDF being the one-pager for MiniScript itself).

Gemini, on the other hand, describes itself as follows:

Gemini is a new internet technology supporting an electronic library of interconnected text documents. That's not a new idea, but it's not old fashioned either. It's timeless, and deserves tools which treat it as a first class concept, not a vestigial corner case. Gemini isn't about innovation or disruption, it's about providing some respite for those who feel the internet has been disrupted enough already. We're not out to change the world or destroy other technologies. We are out to build a lightweight online space where documents are just documents, in the interests of every reader's privacy, attention and bandwidth.

A request in Gemini is a URL followed by a CRLF--nothing more, nothing less. A response is a 2-digit status code, a "meta" line, and then the response body. It's a very simple protocol by design; there are no ways to track someone unless they want to be tracked--Gemini uses TLS client certificates for cases where you'd want to have an account-like system--and no ways to add such a system without breaking compatibility with older clients.

A simple programming language, and a simple network protocol... seems like a match made in heaven!

Part the Second: "What did you accomplish?"

Using a simple proxy server alongside a client running in Mini Micro, you can browse Gemini space using your Mini Micro. There are some limitations (only gemtext and images are properly displayed, there's no client certificate support nor server certificate pinning), but enough is implemented for a quick browse of basic Geminispace.

Part the Third: "How did you do it?"

When you type in a Gemini URL or follow a link, Mini Micro runs startup.ms-- the same file Mini Micro would naturally run on boot. This runs a small code snippet which requests the URL from the proxy server you run alongside it and then dispatches to another script which handles the specific response (displaying the response for 20, or showing error screens for 4x, 5x, or 6x).

Part the Third and a Half: "Why use a proxy server?"

The Gemini protocol is, as I said above, a simple protocol. It runs on raw sockets encrypted with TLS. Unfortunately, Mini Micro doesn't provide support for raw sockets, let alone wrapping them with TLS.

What Mini Micro does support is synchronous HTTP requests. So the fix is simple: write a simple Python script to take HTTP requests and convert them to Gemini.

The proxy, implemented in less than 100 lines of code, parses the gemini URL from the HTTP request path, makes the Gemini request, and then returns to Mini Micro a binary blob containing the canonical URL, the Gemini header line (status and meta), and the body of the response.

The reason we have to return a binary blob with all of this data is because Mini Micro's HTTP support is admittedly quite limited. All it supports is retrieving some resource from a remote server, and all you get back in your program is either the resource (interpreted as Mini Micro sees fit), or null, if there was some error communicating between Mini Micro and the server. As such, the proxy returns the binary blob, which Mini Micro interprets as a RawData, an object specifically made for manipulating binary data, and we can parse the separate fields from it ourselves.

Part the Third and Two Thirds: "But what about the `chrome://` URL in the cover image?"

The chrome:// pages don't actually trigger a request on the proxy; instead, they run a small MiniScript function, which either returns a local file (in the case of chrome://homepage/*) or does some extra logic internally (in the case of chrome://bookmarks/*). This lets the internal logic stay the same; the same utils.request function gets called whether you're passing a Gemini URL or a chrome:// URL, and the response from that function gets handled in the same way.

This also has the secondary benefit of not immediately dropping a new user into an error screen if they aren't running the proxy, since the homepage is implemented as a chrome:// URL.

Part the Fourth: "Why is it interesting or useful?"

To be honest, in the grand scheme of things, it probably isn't. MiniScript is pretty niche, and so is Gemini. But for the handful of people who like both--like myself--it's neat to be able to combine them.

Porting MiniScript to Cosmopolitan Libc

minerobber — Tue, 23 Sep 2025 01:12:53 +0000

There is a lot to be written up. Starting with "wtf is cosmopolitan?" If you leave this now as it is, it will be essentially wasted effort (except for any enjoyment you got out of doing it) — I barely understand what you did, how you did it, and the implications of it, and nobody else is going to get even that far.

It may seem trivial to you, because you already understand all that. 99.9999% of people don't.

It doesn't need to be complicated. Just explain (1) a little background, (2) what you accomplished, (3) how you did it, and (4) why it is interesting/useful.

Then somebody else can come along and appreciate what you've done! 💪

~ Joe Strout, August 27, 2025 (bold emphasis mine)

Alright!

Part the First: "a little background"

Firstly, what is MiniScript, and who is Joe Strout? MiniScript is a programming language that was created in 2016 (first released in 2017) by Joe Strout as an alternative to other programming languages that were/are typically used to teach kids how to program. As the MiniScript homepage states:

This is the home page for MiniScript, a clean, simple language for embedding or learning to program.

MiniScript is modern, elegant, easy to learn, and easy to embed in your own C# or C++ projects. (And elsewhere — there are unofficial ports to TypeScript, Kotlin, and more.)

My favorite thing about MiniScript is that a decently full-featured summary of the entire language fits on one side of a sheet of letter paper. The cheat sheet for Mini Micro, a self-described "neo-retro virtual computer" based around MiniScript, only takes 3 more pages of letter paper to cover pretty much every API that it has (except the ones implemented in MiniScript, which you can read the code of yourself; the fourth page in that PDF, fittingly, is the one-page cheat sheet for the language itself).

Secondly, as Joe put it, "wtf is cosmopolitan?" In the words of creator Justine Tunney:

Cosmopolitan Libc makes C/C++ a build-once run-anywhere language, like Java, except it doesn't need an interpreter or virtual machine. Instead, it reconfigures stock GCC and Clang to output a POSIX-approved polyglot format that runs natively on Linux + Mac + Windows + FreeBSD + OpenBSD 7.3 + NetBSD + BIOS with the best possible performance and the tiniest footprint imaginable.

In layman's terms, Cosmopolitan takes normal C or C++ code and compiles it into a special file. Windows sees it as a normal .EXE file, the other operating systems see it as a shell script (which does some magic to extract the code into a format the operating system in question understands), and in addition to all of that, it's also a .ZIP file, which contains all of the files it needs to be truly portable.

Part the Second: "what you accomplished"

This is the MiniScript C++ command-line interpreter (SHA256 hash: bd802c2be2320739691920f13974f6a5dc950fade387ded8b15b8374e9aa95eb). You can run it on your computer (your antivirus might complain, and/or you may need to do some tricks to make it work if you're on a Mac, but by and large it should Just Work). It contains all of the libraries that "come with" the command-line interpreter (dateTime, grfon, importUtil, json, listUtil, mapUtil, mathUtil, matrixUtil, qa, stringUtil, tsv, and vt) inside the executable (this is where the .ZIP file part above comes in handy).

If you write a script with it and want to share that script as a self-contained executable in its own right, the steps are simple:

Copy miniscript.com and rename the copy to something like MyAwesomeProgram.com or whatever you want (it only really needs a file extension if you're on Windows).
Change the file extension of MyAwesomeProgram.com to .zip.
Copy your script (and any libraries you imported) into the .zip.
Write a .args file containing the filename of your script preceded by /zip/ (so MyAwesomeProgram.ms would be put in there as /zip/MyAwesomeProgram.ms), and place that in the .zip file as well.
Finally, change the file extension back to .com (or remove it if you don't need it).

Now, when you run MyAwesomeProgram.com, it should run your script!

Part the Third: "how you did it"

Well, first, compiling a cmake project like MiniScript using Cosmopolitan's "cosmocc" compiler has been done before; I personally followed (and suggest following to anyone doing something similar) these instructions by Jacob Hummer. I did have to modify MiniScript's whereami.c to properly handle Cosmopolitan as a platform, but that was really easy and basically amounted to making a WAI-shaped wrapper for the Cosmopolitan function GetProgramExecutableName (after I was told that function existed). Doing just that is enough to get a functional, if odd, MiniScript install; it says it's running on Linux, for some reason, and it's missing a lot of features common to Cosmopolitan projects, like support for .args, use of storing files in the ZIP, etc.

Luckily, these features are somewhat easy to add. In the case of "it says it's a command line interpreter for Linux", Linux is just what it defaults to if it doesn't think it's running on something else, so correctly reporting ourselves as a Cosmopolitan interpreter is as easy as just adding a case for __COSMOPOLITAN__. Storing files in the .ZIP portion of the executable ("ZipFS" in Cosmopolitan parlance) is automatically supported by the runtime, so we just need to tell MiniScript to go look there; in my actual implementation I moved the definition of the default import path into ShellIntrinsics.h, so I could add /zip/lib to the end if and only if we were compiling for Cosmopolitan. As for .args, the function in Cosmopolitan that implements this is called cosmo_args, so it's just a matter of calling that before we do anything with arguments. I did a little fancy stuff so that argv could be defined as const when not compiling for Cosmopolitan (no reason not to, and that's what it was before I got to the code), but not be defined as const when we were compiling for Cosmopolitan (since cosmo_args, by definition, modifies argv).

Part the Fourth: "why it is interesting/useful"

With this finished, MiniScript joins the ranks of programming languages like Janet, Lua(JIT), Perl, PHP, Python, and Tcl in having been ported to Cosmopolitan. The idea of being able to package everything you need to write command-line MiniScript programs into a single file--and then package that program as a single-file click-it-and-run executable of its own--well...