An extensible, general purpose http->gemini mirror with full javascript support, live at gemini://
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

3.7 KiB

hellgate logo

An extensible, general purpose http->gemini mirror with full javascript support

Requirements - If you are using Docker

  • docker

Requirements - If you are not using Docker

  • nodejs
  • npm
  • electron
  • openssh
  • sh
  • libgtk-2-0
  • libgconf-2-4
  • libxshmfence1
  • libnss3
  • libatk-bridge2.0-0
  • libdrm2
  • libgtk-3-0
  • libgbm
  • libasound2
  • xvfb (if you're running it headless)

Setup - If you are using Docker

  • docker pull sose/hellgate
  • docker run -p 1965:1965 sose/hellgate
  • the server will listen on localhost:1965
  • If you are using port 1965 on the host machine, you can bind a different port by running docker run -p {PORT}:1965 sose/hellgate instead

Setup - If you are not using Docker

  • sudo apt install npm nodejs libgtk2.0-0 libgconf-2-4 libxshmfence1 libnss3 libatk-bridge2.0-0 libdrm2 libgtk-3-0 libgbm1 libasound2 (if you're on debian, other distros idk)
  • sudo apt install xvfb (again, on debian)
  • git clone
  • cd hellgate
  • sudo npm install -g electron --unsafe-perm=true
  • npm install
  • ./gen_cert
  • npm start or xvfb-run npm start
    • The server will listen on [::1]:1965 by default


  • Supply a full url in the query string in a request to the server and it will be rendered in Gemtext
  • ex. gemini://localhost?
  • You have to include the scheme or Hellgate will not recognize it


  • By default, more complex sites that are rendered by hellgate are not very pretty, and sometimes downright unreadable
  • For this, users can create website specific 'sigils' to display content in a certain way, or to automate certain actions on a website
  • Sigils are located in the sigils dir and are titled with the domain name of their corresponding website
  • See writing sigils for more info on how to write sigils and how they work
  • If you write a new sigil for a specific website, don't hesitate to send it as a pull request to this repo


  • Obviously, executing arbitrary Javascript from around the web is never going to be completely safe, however the following steps have been taken to ensure the saftey of the host machine:
    • All websites have a maximum time in which they have to load their content (default 2s) and execute any scripts (default 2s)
    • When running outside of a Docker container, all renderer processes will be run inside the Chromium sandbox (
    • When running inside of a Docker container, the entire program is running inside a Docker container (as an unprivileged user).
    • Nodejs integration is disabled in all renderer processes
    • Context isolation is enabled in all reneder processes
    • Any request for browser permissions is automatically denied
    • Any request to create a new window is automatically denied
  • Essentially, in theory, the machine hosting hellgate should not be at any more risk than a regular web broser. However, security vulnerabilities exists, and no software is perfect, not Docker, not Chromium, not Linux not Electron and certainly not Hellgate. If you have valuable things on your server I would suggest running all of this in a VM, just in case.

Other Notes

  • This isn't a proxy meant to be run on the user's machine, rather many users are meant to connect to a single hosted version, such as gemini:// I would never want you to install npm on your machine :)
  • As of right now the npm version of gemini-server is broken, use the version from github or this will not work.
  • If you are using the docker container this is already done for you.