# Install, system requirements & supported platforms

Source: https://humanymous.net/reference/install-requirements.html
Project: humanymous — defensive anti-bot / browser-automation detection (Apache-2.0).

---

# 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](../tutorials/quickstart-monitor-mode.md).

> **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](production-vs-reference.md) for the full list.

## Toolchain

| Requirement | Value |
|---|---|
| Go toolchain | go 1.25.3 (declared in `go.mod`) |
| CGO | Not used — pure Go |
| Direct dependencies | Four: `github.com/refraction-networking/utls` v1.8.2 (uTLS), plus `golang.org/x/crypto` v0.54.0, `golang.org/x/net` v0.57.0, `golang.org/x/text` v0.40.0 |

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](../concepts/how-gate-sees-a-request.md)) — 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](#run-from-the-published-image-no-build) 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](../how-to/deployment-policy-operations.md#recipe-stand-up-the-admin-listener-with-seeded-role-tokens).

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 you@your.domain -monitor
```

The certificate issues automatically via TLS-ALPN-01 and renews itself; see [HTTPS / TLS certificates](../how-to/https-tls-certificates.md) 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](../how-to/run-detection-engine.md) 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.

| Port | Role | Flag / source |
|---|---|---|
| `:8444` | Public edge (HTTPS) — terminates TLS, injects the detection bundle, scores L1–L7, and enforces the verdict | `-addr ":8444"` |
| `:8445` | Separate authenticated admin listener (Ledger + admin API), cross-origin to the edge | `-admin-addr ":8445"` |
| `:9000` | Your origin app that Gate proxies to (the `-upstream` target) | `-upstream "http://127.0.0.1:9000"` |

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](cli-config-policy.md).

> **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](../how-to/key-management.md)).
- 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](production-vs-reference.md).

## 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](../tutorials/quickstart-monitor-mode.md), then read the [integrator start-here guide](../start-here/integrator.md) for how to place Gate in front of your origin.

## Related pages

- [Monitor-mode quickstart](../tutorials/quickstart-monitor-mode.md) — your first run, end to end.
- [CLI, config & policy](cli-config-policy.md) — every flag, preset, and route default.
- [Production vs reference](production-vs-reference.md) — the complete prod-delta list.
- [Integrator start-here](../start-here/integrator.md) — putting Gate in front of your app.
- [How Gate sees a request](../concepts/how-gate-sees-a-request.md) — the L1–L7 detection model.