Gemini server
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.

2.8 KiB

twins requires a configuration file to operate. By default, it is loaded from ~/.config/twins/config.yaml. You may specify a different location via the --config argument.

Configuration options


Address to listen for connections on in the format of interface:port.

Listen on localhost


Listen on all interfaces



At least one certificate and private key must be specified, as Gemini requires TLS.

localhost certificate

Use openssl generate a certificate for localhost.

openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -config <( \
   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Domain certificate

Use certbot to get a certificate from Let's Encrypt for a domain.

certbot certonly --config-dir /home/www/certs \
  --work-dir /home/www/certs \  
  --logs-dir /home/www/certs \
  --webroot \
  -w /home/www/ \
  -d \

Provide the path to the certificate file at certs/live/$DOMAIN/fullchain.pem and the private key file at certs/live/$DOMAIN/privkey.pem to twins.


Hosts are defined by their hostname followed by one or more paths to serve.

Paths may be defined as fixed strings or regular expressions (starting with ^).

Paths are matched in the order they are defined.

Fixed string paths will match with and without a trailing slash.

When accessing a directory the file index.gemini or index.gmi is served.

Path attributes


Serve static files from specified root directory.

Directory listing may be enabled by adding listdirectory: true.


Forward request to Gemini server at specified URL.

Use the pseudo-scheme gemini-insecure:// to disable certificate verification.


Serve output of system command.

Example config.yaml

# Address to listen on
listen: :1965

# TLS certificates
    cert: /home/
    key: /home/

# Hosts and paths to serve
      path: /sites
      root: /home/
      listdirectory: true
      path: ^/(help|info)$
      root: /home/
      path: ^/proxy-example$
      proxy: gemini://localhost:1966
      path: ^/cmd-example$
      command: uname -a
      path: /
      root: /home/
      path: /sites
      root: /home/twins/data/sites
      path: /
      root: /home/twins/data/home