spacecookie: Gopher server library and daemon

[ gpl, library, network, program ] [ Propose Tags ]

Simple gopher library that allows writing custom gopher applications. Also includes a fully-featured gopher server daemon complete with gophermap-support built on top of it.

[Skip to Readme]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,,,,
Change log
Dependencies aeson (>=1.5), async (>=2.2), attoparsec (>=0.13), base (>=4.9 && <5), bytestring (>=0.10), containers (>=0.6), directory (>=1.3), fast-logger (>=2.4.0), filepath-bytestring (>=1.4), hxt-unicode (>=9.0), mtl (>=2.2), socket (>=0.8.2), spacecookie, systemd (>=2.1.0), text (>=1.2), transformers (>=0.5), unix (>=2.7) [details]
License GPL-3.0-only
Author Lukas Epple
Category Network
Home page
Bug tracker
Source repo head: git clone git://
head: git clone git://
Uploaded by sternenseemann at 2022-10-03T18:47:30Z
Distributions NixOS:
Executables spacecookie
Downloads 1716 total (38 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2022-10-03 [all 1 reports]

Readme for spacecookie-

[back to package description]


Haskell gopher server daemon and library.


  • implements RFC1436
  • optionally supports common protocol extensions:
  • supports gophermaps (see below)
  • supports systemd socket activation
  • provides a library for custom gopher applications (see documentation)


spacecookie intentionally does not support:

  • HTTP, Gemini: Multi protocol support is a non-goal for spacecookie. For HTTP you can proxy pretty easily, however.
  • Search: Gopher supports search transactions, but the spacecookie daemon doesn't offer the possibility to add a search engine to a gopherspace. It is however entirely possible to implement an index search server using the spacecookie library




spacecookie is configured via a JSON configuration file. All available options are documented in spacecookie.json(5). This repository also contains an example configuration file in etc/spacecookie.json.


After you've created your config file just start spacecookie like this:

spacecookie /path/to/spacecookie.json

spacecookie runs as a simple process and doesn't fork or write a PID file. Therefore any supervisor (systemd, daemontools, ...) can be used to run it as a daemon.

With systemd

spacecookie supports systemd socket activation. To set it up you'll need to install spacecookie.service and spacecookie.socket like so:

cp ./etc/spacecookie.{service,socket} /etc/systemd/system/
systemctl daemon-reload
systemctl enable spacecookie.socket
systemctl start  spacecookie.socket
systemctl start  spacecookie.service # optional, started by the socket automatically if needed

Of course make sure that all the used paths are correct!

How the systemd integration works is explained in spacecookie(1).

On NixOS

NixOS provides a service module for spacecookie: services.spacecookie. Setting up spacecookie is as simple as adding the following line to your configuration.nix:

services.spacecookie.enable = true;

For all available options, refer to the NixOS manual:

Adding Content

spacecookie acts as a simple file server, only excluding files or directories that start with a dot. It generates gopher menus automatically, but you can also use custom ones by adding a gophermap file.

spacecookie checks for .gophermap in every directory it serves and, if present, uses the menu specified in there.

Such a file looks like this:

You can just start writing text that
will be displayed by the gopher client
without a link to a file. Empty lines are
also possible.

1Menu Entry for a directory full of funny stuff	/funny
IFunny Image	/funny.jpg
gcat gif	/cat.gif
0about me	/about.txt
1Floodgap's gopher server	/	70

As you can see, it largely works like the actual gopher menu a server will send to clients, but allows to omit redundant information and to insert lines that are purely informational and not associated with a file. spacecookie.gophermap(5) explains syntax and semantics in more detail.

The format is compatible with the ones supported by Bucktooth and pygopherd. If you notice any incompatibilities, please open an issue.


spacecookie is regularly tested on GNU/Linux via CI, but should also work on other Unix-like operating systems. Most portability problems arise due to haskell-socket which is for example known not to work on OpenBSD.

Windows support would be possible, but could be tricky as gopher expects Unix-style directory separators in paths. I personally don't want to invest time into it, but would accept patches adding Windows support.