Chihaya runs two tracker protocols behind a YAML middleware chain

The tag history and the README warning do not agree

The release history is the first thing to look at, and it needs an explanation.

The recent releases are v2.0.0-rc.2 dated 2017-06-09, v2.0.0-rc.1 from 2016-11-11 and v1.0.2 from 2016-09-30. So the newest tagged release is a release candidate from nine years ago, while the last push to the default branch is on 2026-09-01, under two months before today.

Against that, the README carries an explicit note: the master branch may be in an unstable or even broken state during development, and you should use releases instead of the master branch in order to get stable binaries. The default branch is `main`, and the module targets `go 1.25.0` with a `toolchain go1.26` directive, which could not have compiled in 2017.

So the practical reading is that the tags are stale and the branch is the live work. The README's own advice points at the wrong place by the evidence, and reconciling that is your first task as an adopter: read the commit history on `main`, or build from a commit you have read rather than from a tag or a moving branch.

Nothing in the repository listing suggests the tags were deleted, so this looks more like neglect of the release process than a deliberate withdrawal. Either way the operational consequence is the same, and it is worth stating plainly: you are tracking a project with no current release artefacts.

Building from a checkout is the documented path, and it needs the latest stable Go plus a working Go environment:

git clone [email protected]:chihaya/chihaya.git
cd chihaya
make build
./bin/chihaya --help

Container images are published on quay.io for both HEAD and stable releases, as `jzelinskie/chihaya-git` for HEAD and `jzelinskie/chihaya` for stable.

Two protocols, two ports, and a non-root container

The differentiating features are listed as HTTP and UDP protocols, IPv4 and IPv6 support, pre and post middleware hooks, YAML configuration, Prometheus metrics, Redis high availability and Kubernetes deployment through Helm.

The protocol split is the standard tracker design. HTTP trackers use announce and scrape requests over HTTP, which works through any proxy but costs a request per operation. UDP trackers answer over a datagram protocol with no connection overhead, which is what makes them fast and cheap for large swarms, at the cost of being harder to operate. Supporting both means clients and internal components can choose.

The container image shows which ports that maps to. The Dockerfile is a two-stage build on `golang:alpine`, compiling with `CGO_ENABLED=0 go install./cmd/chihaya`, then copying the binary into a minimal `alpine` image with only `ca-certificates` added. It exposes `6880 6969`, which are the conventional BitTorrent tracker ports, adds a dedicated user with `adduser -D chihaya`, drops to it with `USER chihaya`, and sets `ENTRYPOINT ["/chihaya"]`. The Dockerfile creates a dedicated `chihaya` user and configures the container to run as that user.

The IPv4 and IPv6 support claim matters operationally rather than as a checkbox. A tracker listening on one family is unreachable by half your clients, and dual-stack listeners need the proxy in front to pass both families.

For metrics, `prometheus/client_golang` 1.23.2 is a direct dependency, so instrumentation is built in rather than bolted on.

Middleware is the integration point, not a plugin system

The README frames Chihaya as built for developers looking to integrate BitTorrent into a preexisting production environment, and names the pluggable architecture and middleware framework as the integration point that abstracts the tracker protocols.

That is an accurate description of what middleware means here. Pre and post middleware hooks wrap request handling, so a cross-cutting concern like authentication, rate limiting, logging or metrics is a configured component rather than code inside the tracker. The repository layout is organised around this: a `middleware/` directory at the top level, plus `bittorrent/` for the protocol layer, `storage/` for persistence implementations, `pkg/` for shared code and `cmd/` for the command entry point. Files and directories under `docs/` are said to contain detailed information about configuring middleware, storage implementations and architecture.

Configuration is a single YAML file. The `dist/` directory holds example configuration files, and the Makefile references two of them by name, `./dist/example_config.yaml` and `./dist/example_config_redis.yaml`, which tells you there is one memory-backed configuration and one Redis-backed configuration shipped as examples.

The storage abstraction is where the Redis high availability claim lives. `go-redsync/redsync/v4` provides distributed locking across processes, and `gomodule/redigo` is the Redis client, which together suggest multiple tracker instances coordinate through Redis rather than requiring a sticky load balancer.

A `frontend/` directory at the repository root is worth noting. The README does not describe it, and a tracker with a web frontend is worth understanding before you expose it, because that is an additional attack surface with its own authentication expectations.

The Makefile runs a real test matrix, including a Helm template check

The build and test surface is small enough to read in full, and it tells you how the project is validated.

Building is `go build -o "bin/chihaya" ./cmd/...`, with a `VERBOSE` variable that adds `-v`. Container builds are `docker build -t chihaya:dev .`, and benchmarks are `go test ./... -bench=. -benchtime=5s`.

`make test` is not one command. It chains `test-unit test-e2e test-helm`. The unit target is `go test -failfast -race -count=1 -timeout=5m ./...`, so the race detector runs on every unit test.

The end-to-end targets exercise the real binary rather than calling into packages. `test-e2e-mem` builds the binary into a temporary directory, launches it with `./dist/example_config.yaml --debug` in the background, sleeps, then runs `chihaya e2e --debug`. The project therefore has an `e2e` subcommand on the binary itself, so the same executable that serves tracker requests can drive an end-to-end scenario. Both e2e targets set shell traps to clean up the temporary directory and kill the background processes.

`test-e2e-redis` repeats the pattern with a `redis-server --save ""` started in the background and the Redis-backed config file. Running the identical scenario against both storage backends is how the Redis path stays honest.

`test-helm` runs `helm template . --debug` inside `./dist/helm/chihaya`, so the chart is validated by rendering it. That catches a broken template without deploying anything.

Linting is split four ways: `gofumpt` for formatting, `go mod tidy -diff` for module hygiene, `golangci-lint` v2 and `yamlfmt -lint` for YAML. All four are declared as Go tool dependencies in the module rather than installed separately, which is what the `tool` directive in `go.mod` is for, and it means linter versions are pinned by the module graph. There are `fix-fmt` and `fix-gomod` targets to apply the corrections.

What it is for, and where the boundaries are

The stated use case is specific: enabling peer-to-peer cloud software deployments. Chihaya is positioned as a component in someone else's product, not as a standalone service for the public torrent ecosystem.

That framing shapes how you read the comparison projects the README lists. BitTorrent.org is the specification site with all the BEPs. OpenTracker is a tracker written in C and described as popular. Ocelot is a private tracker in C++. All three are references: the first for what the protocols require, the other two for what an alternative implementation looks like.

On boundaries, a tracker is infrastructure with one job, and Chihaya's scope is that job plus the integration points. It does not ship a web client, a torrent index, a content catalogue or anything about the content being distributed. If you are evaluating a BitTorrent client or a private tracker with a user interface, this is the wrong layer.

Two operational limits are worth naming. First, licensing needs reading directly. The README badge points at the two-clause BSD licence on Wikipedia, while the repository's licence classification is recorded as a custom licence GitHub cannot categorise, with a `LICENSE` file at the root. Read that file rather than the badge.

Second, the maintenance picture is the real constraint. The repository is not archived and the last push was on 2026-09-01, so work is happening. But with no release since 2017, the gap between the README's advice and the repository state is where your risk sits.

The module also directly depends on several libraries, including `cobra` 1.10.2, `lmittmann/tint` 1.1.3, `httprouter` 1.3.0, `pkg/errors` 0.9.1 and `anacrolix/torrent` 1.61.0.

Editorial conclusion

Chihaya fits a team that needs a tracker as an internal component in an existing Go service, with the ability to add policy in middleware rather than forking. Do not adopt it expecting a tagged release stream, because the newest release in the history is from 2017 and the README advises using releases for stable binaries, which leaves you reading commit history to judge stability. Verify first whether the example configurations in the dist/ directory and the Helm chart still match your deployment, and pin a commit rather than tracking the branch.

Frequently asked questions

Official sources

1. chihaya/chihaya on GitHub
2. Issues
3. Project website
4. README
5. Releases