It automatically fetches the public Kittygram instance list, checks instance health, and can optionally store recent uptime history in SQLite. The goal is to make it easy to find a working Kittygram instance.

You can use it at redirect.kittygr.am.

Hosting your own

With Docker/Podman

We have pre-built images you can run. To run the latest version of kittygram-redirect:

docker run -p18956:18956 foundry.fsky.io/fsky/kittygram-redirect:latest

If you are using Podman, the process is the same. Just replace docker with podman in the command.

To enable optional uptime history, mount a writable directory at /data:

docker run -p18956:18956 \
  -e ENABLE_UPTIME_HISTORY=true \
  -v kittygram-redirect-data:/data \
  foundry.fsky.io/fsky/kittygram-redirect:latest

Uptime history is recorded from the same health checks used by the redirector. Clearnet instances are checked by default. Tor, I2P, and Yggdrasil history is recorded when their matching PROBE_* option is enabled.

Quadlet

You can find a Quadlet file in contrib/quadlet/kittygram-redirect.container. Download it and place it into /etc/containers/systemd/ or ~/.config/containers/systemd/. After that, run:

systemctl --user daemon-reload
systemctl --user start kittygram-redirect.service

Build from source

This program is written in Go. You need Go 1.25 or later.

You can build a binary using:

go build

Configuration

The application can be configured using the following environment variables:

The instance list is fetched from upstream Kittygram on Codeberg first. If Codeberg is unavailable, the app falls back to the mirror at https://foundry.fsky.io/mirrors/kittygram/raw/branch/main/instances.json.

Variable	Description	Default
`PROBE_TOR`	Enable health checks and uptime history for Tor instances	`false`
`PROBE_I2P`	Enable health checks and uptime history for I2P instances	`false`
`PROBE_YGGDRASIL`	Enable health checks and uptime history for Yggdrasil instances	`false`
`TOR_PROXY`	Proxy URL for Tor health checks	`socks5://127.0.0.1:9050`
`I2P_PROXY`	Proxy URL for I2P health checks	`http://127.0.0.1:4444`
`ENABLE_UPTIME_HISTORY`	Store health check history in SQLite and show recent uptime data	`false`
`UPTIME_DB_PATH`	SQLite database path for uptime history	`/data/kittygram-redirect.sqlite`
`UPTIME_RETENTION_DAYS`	Number of days of raw uptime checks to keep	`30`

License

This project is released into the public domain under the Unlicense.