Install, system requirements & supported platforms

Diátaxis quadrant: Reference. Audience: integrators standing up humanymous Gate for the first time (step zero).

This page lists exactly what you need to build and run the reference implementation of humanymous Gate: the toolchain, the one dependency, the build command, the ports it listens on, and the external services it does not need. It is a lookup, not a walkthrough — when you are ready to run, follow the monitor-mode quickstart.

Note: This repository is a reference implementation, not a production-hardened build. Several things a production deployment would need (shared fleet state, a real key-management service, CA-issued certificates, and more) are prod-delta and are not present here. See production vs reference for the full list.

Toolchain

Gate is written in pure Go with no CGO. That keeps the build simple and lets you cross-compile for any target with GOOS/GOARCH — you do not need a C compiler or platform-specific build tooling.

The Go module is github.com/modootoday/humanymous. It has four direct dependencies: uTLS — which Gate uses to read TLS ClientHello fingerprints (part of the L5 network layer — see how Gate sees a request) — plus the golang.org/x/crypto, golang.org/x/net, and golang.org/x/text extended standard-library packages. uTLS is the only non-golang.org/x third-party dependency.

Supported platforms

Because the build is pure Go, Gate builds and runs on Linux, macOS, and Windows via the standard Go cross-compilation flags (GOOS/GOARCH).

The build command below writes bin/gate.exe. The .exe name reflects a Windows development host — it is just an output filename, not a platform constraint. On Linux or macOS, name the output whatever suits your OS (for example, bin/gate).

TODO(verify): Minimum and recommended hardware sizing (RAM, CPU cores) for the edge and admin listeners is not specified in the verified facts.

Confirmed in source: Because Gate is pure Go with no CGO, the supported target matrix is every GOOS/GOARCH pair the Go toolchain supports — including linux, darwin, and windows on amd64 and arm64 — selected via cross-compilation flags. The only build-constrained code is the browser detection engine (js/wasm); the server binaries carry no OS/arch constraints. The toolchain floor is the go directive in go.mod: Go 1.25.3. Specific OS version floors (minimum Linux kernel, macOS, or Windows release) are not constrained in the build and Gate imposes none in code; treat them as operator-determined.

Note: Prebuilt multi-arch images are published to GitHub Container Registry — ghcr.io/modootoday/humanymous-gate:latest and ghcr.io/modootoday/humanymous-core:latest (Apache-2.0, linux/amd64 + linux/arm64, cosign-signed) — so you can run without building (see Run from the published image below). Container packaging also lives in the repository under build/ — build/core.Dockerfile (the detection engine) and build/gate.Dockerfile (Gate), both on a gcr.io/distroless/static-debian12:nonroot base, wired for local builds in deployments/compose.yaml.

Build

Build the edge binary from the repository root:

go build -o bin/gate.exe ./cmd/gate

On Linux or macOS, substitute an OS-appropriate output name, for example:

go build -o bin/gate ./cmd/gate

To cross-compile from one host for another target, set GOOS and GOARCH before the build (for example, GOOS=linux GOARCH=amd64). No CGO toolchain is required.

Run from the published image (no build)

You do not have to build Gate to run it. Pull the published image and run it in front of your origin — no Go toolchain, no source tree. The image is linux/amd64 + linux/arm64, so it runs natively on Intel/AMD and ARM (Apple Silicon, Graviton, Raspberry Pi).

docker run -d -p 8444:8444 -p 127.0.0.1:8445:8445 \
  ghcr.io/modootoday/humanymous-gate:latest \
  -addr :8444 -admin-addr :8445 -upstream http://YOUR-ORIGIN:PORT -monitor

• :latest tracks the newest release.
• -monitor scores and logs without enforcing — the safe first contact with real traffic. Drop it to enforce.
• The admin listener is mapped to host loopback only (127.0.0.1:8445); keep it that way or front it with mTLS/SSO.
• To actually reach the console/audit API on :8445, set an admin token — the command above maps the port but sets none, so Gate mints random per-boot tokens it does not print and the API is unreachable. Add -e HMN_ADMIN_TOKENS=operator:<random-16+-char-secret> (repeat comma-separated per role: auditor:…,operator:…,approver:…,dpo:…), or -e HMN_ALLOW_DEV_TOKENS=1 for a throwaway local demo. See Stand up the admin listener.

To present a real Let’s Encrypt certificate instead of the self-signed dev cert (public domain, inbound :443, and a persistent ACME cache volume), add the ACME flags and publish :443:

docker run -d -p 443:8444 -p 127.0.0.1:8445:8445 \
  -v hmn-acme:/acme-cache \
  ghcr.io/modootoday/humanymous-gate:latest \
  -addr :8444 -admin-addr :8445 -upstream http://YOUR-ORIGIN:PORT \
  -acme-domain your.domain -acme-cache /acme-cache -acme-email [email protected] -monitor

The certificate issues automatically via TLS-ALPN-01 and renews itself; see HTTPS / TLS certificates for the full walkthrough, a staging dry-run, bring-your-own PEMs, and running behind an existing TLS terminator.

For a full production deployment (ACME TLS, sealed keystore, durable audit WAL, hardened read-only container), use the pull-only Compose file, which references the published images directly:

cd deployments
cp .env.example .env            # HMN_UPSTREAM, HMN_DOMAIN, HMN_UNSEAL, HMN_ADMIN_TOKENS
cp routes.conf.example routes.conf
docker compose -f compose.release.yaml up -d

The detection engine is published too, as ghcr.io/modootoday/humanymous-core:latest (for standalone self-testing / the demo). See Run the detection engine for the full Core runbook (flags, ports, and the published-image docker run recipes).

Ports

The reference runs three localhost listeners. Two are Gate’s own; the third is your origin application, which Gate fronts.

The admin listener is deliberately separate from the public edge: /__hmn/admin/* is not reachable on the edge and returns 404 there. The Ledger is served at https://localhost:8445/__hmn/admin/console. For the full flag list and defaults, see CLI, config & policy.

Note: These are the reference defaults. Each is configurable through the flag shown; the origin base URL in particular will point at wherever your application actually listens.

External service dependencies

In the reference, there are none. Gate holds its state in memory in a single process:

• The verdict store, rate-limit counters, and bans are in-process (single node).
• The audit log, keys, and pseudonym vault live in-process (optionally sealed to a local keystore file with -keystore plus the HMN_UNSEAL passphrase — see key management).
• The development TLS certificate is self-signed in memory.

You do not need a database, Redis, or a key-management service to run the reference.

Important: Shared fleet state (for example, Redis-backed verdict store and bans), a real KMS/HSM, and CA-issued certificates are prod-delta — they are what a production deployment would add, and they are not part of this reference. Do not plan a multi-node deployment on the assumption that shared state exists here; it does not. See production vs reference.

First run

Once the binary builds, start with monitor mode so Gate scores and logs traffic without enforcing any verdict. Follow the step-by-step monitor-mode quickstart, then read the integrator start-here guide for how to place Gate in front of your origin.

Related pages

• Monitor-mode quickstart — your first run, end to end.
• CLI, config & policy — every flag, preset, and route default.
• Production vs reference — the complete prod-delta list.
• Integrator start-here — putting Gate in front of your app.
• How Gate sees a request — the L1–L7 detection model.