wangwanjie/gately

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский | Português (Brasil)

An open-source, auditable network gateway toolkit for home networks, NAS boxes, cloud hosts, and servers of all kinds. DDNS, STUN traversal, port forwarding, reverse proxy, certificates, WAF, and more ship in a single ~32 MB file, and existing Lucky configurations can be imported.

Gately is fully open source, so users and the community can read the source and the configuration directly. For software that sits on your network edge and holds your DNS keys and certificate private keys, open source lets you see exactly what it does. Gately's commitments:

• The source is released under Apache-2.0 and open to community review
• No connections to any project-operated server by default and no device information reported; third-party sign-in uses your own OAuth apps, with no relay in between
• Every outbound address (public IP lookup, STUN servers, and so on) is visible, editable, and can be turned off
• Configuration is plain-text JSON, so you can put it under git for auditing and rollback

Images are available for amd64, arm64, and arm/v7:

docker run -d --name gately --network host \
  -v ./gately-data:/etc/gately \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/wangwanjie/gately:latest
docker logs gately 2>&1 | grep -i "initial password"

Open http://<device-ip>:16680 and sign in as admin with the initial password from the log. Then change the password and enable two-factor authentication under Settings. See deploy/docker-compose.yml for a complete Compose example.

Port forwarding, STUN, and web services listen on host ports, so --network host is recommended. If you do not need Docker management, drop the docker.sock mount.

Download the archive for your platform from Releases (Linux amd64/arm64/arm/mips/mipsle/riscv64, macOS, Windows, FreeBSD), extract it, and run:

./gately -c /etc/gately

Flags: -c sets the config directory (the GATELY_CONFIG_DIR environment variable also works), -listen overrides the admin UI listen address, -apply applies <name>.json files from a directory to the config directory on every start (GATELY_APPLY_DIR, handy for GitOps and Kubernetes; the account and token files cannot be overwritten), and -version prints the version. For unattended installs, set GATELY_INITIAL_PASSWORD to choose the initial admin password instead of reading a random one from the log.

Service templates: systemd and OpenWrt procd. To verify downloaded archives and images (cosign signatures, build provenance, SBOM), see Verifying release artifacts.

Create an API token with only the metrics:read permission and point Prometheus at /api/metrics. Metrics, alert examples and the Grafana dashboard are described in Monitoring.

Create a token on the "API Tokens" page of the admin console. You can create several, grant each read-only or read-write access per module, set an expiry, and the plaintext is shown only once, right after creation. Scripts can then call the admin API in bulk:

curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/ddns/tasks

Account, two-factor authentication, and token management, as well as the backup, restore, restart, and system settings endpoints, accept login sessions only. All endpoints, required permissions, and data schemas are listed on the "API Docs" page of the admin console. You can also export them to docs/api/en (openapi.json and API.md) with make api-docs; the website https://gately.cn references them directly when published.

When upgrading from an older version, the previous global API token becomes a "legacy token" automatically (same value, full access to every module). Tighten its permissions or replace it with a new token on the API Tokens page.

These three modules manage the official external programs (automatic restart, logs aggregated in the UI). Gately does not bundle them, so you can always run the latest upstream release. Programs are located in this order: the path set in the module settings, PATH, then the bin/ subdirectory of the config directory. For Docker deployments, drop the binary into the mounted config directory, for example ./gately-data/bin/frpc; Tailscale needs both tailscale and tailscaled. Tokens and keys in config files are stored with 0600 permissions, and the cloudflared token is passed via an environment variable so it never appears in the process list.

See the migration guide. In short: under "Settings → Import from Lucky", choose the lucky_*.lkcf file from your Lucky config directory, preview it, then import. Imported rules are disabled by default; go module by module, disabling in Lucky and enabling in Gately.

Requirements: Go 1.26+, Node.js 24+, pnpm.

make web      # build the frontend (outputs to web/dist, embedded via go:embed)
make build    # compile bin/gately
make test     # go test -race ./...
make lint     # gofmt, go vet, frontend type check

For frontend development, run cd web && pnpm dev; /api is proxied to local 127.0.0.1:16680.

Some tests are skipped by default and need extra setup:

For the directory layout and technology choices, see docs/ROADMAP.md.

The website (gately.cn) source lives in website/ and is built with VitePress: cd website && pnpm install && pnpm dev; pnpm deploy:site builds and syncs it to the server.

• Lucky compatibility is based on publicly observable behavior, interfaces, and configuration formats. Do not submit code copied from Lucky binaries or frontend bundles.
• A new module needs a config schema with validation, runtime start/stop, REST endpoints, and unit tests. Modules that can be migrated from Lucky implement luckyimport.Importer; modules that want to show status on the overview page implement module.Summarizer.
• Code comments are written in Chinese; control statements must use braces.

Questions, feedback and usage tips are welcome in the Telegram group: t.me/gately_chat. Please report bugs in GitHub Issues and attach a diagnostics bundle (Settings → Diagnostics); it is generated locally and contains no passwords, tokens, domains or real IPs.

Apache License 2.0