Agena is a so-called Gemini-to-Gopher proxy. It is simultaneously a Gemini server and a Gopher client, and can translate Gopher menus into gemtext documents. Any Gemini client can be turned into a combined Gemini and Gopher client with very little effort and without writing a line of Gopher-specific code, simply by extending it to "farm out" gopher:// to an Agena instance. Agena can listen for TLS connections arriving via TCP/IP (in which case it needs to be provided with a TLS certificate and matching private key), or on a Unix domain socket (in which case no certificate is required).
Agena is not yet known to be packaged by any operating system repositories. Your installation options are to use pip or to install manually after getting a local copy of the code (see section "Code" below).
Agena is installable via pip, with the command `pip install Agena`.
Agena has no true dependencies beyond the Python standard library. However, if the `chardet` package is installed, it will enable Agena to serve Gopher content encoded with encodings other than UTF-8 or ISO-8859-1. Note that if you've installed Agena with `pipx` (because your Linux distribution offers a so-called "externally managed Python environment" but doesn't have a package for Agena), but you have installed `chardet` with the system package manager, Agena won't be able to "see" `chardet` from within the virtual environment that pipx needlessly creates for it. In this scenario you need to run `pipx inject Agena chardet`.
Because Agena consists of a single .py file and has no mandatory dependencies, if for any reason you are unable to use `pip` you can just drop a copy of agena.py in ~/bin, ~/.local/bin, /usr/local/bin (this last option typically requiring root) or anywhere else in your $PATH without worrying about "proper installation" and it will Just Work.
Agena development happens in the git repo at https://git.sr.ht/~solderpunk/agena. You can run `git clone https://git.sr.ht/~solderpunk/agena` to get a local copy.
Agena code was previously hosted at https://tildegit.org/solderpunk/Agena but this repository is deprecated as of January 2025 and will not be used any more.
The Agena git repository contains a man page in the `docs/` directory, `agena`(1), and this is the authoritative documentation for how to configure, understand and us Agena. If you installed Agena with `pip` or `pipx`, the man page won't have been installed at the same time (pip doesn't support it). You can always install the man page manually after cloning the repository (see above), but for your convenience there is also a pre-formatted 70 column ASCII version of the man page accessible via Gemini here:
agena(1) - documents all command line optionsAgena is named after the Agena Target Vehicle (ATV), used by NASA during its Gemini program (after which the Gemini protocol is named) to develop and practice orbital docking techniques.