AGENTS.md

Project

github.com/fatedier/frp — fast reverse proxy. Go 1.25. Two binaries:

Command	What
`make build`	Build both binaries to `bin/`
`make frps` / `make frpc`	Single binary
`make all`	`fmt → web → build`
`make web`	Build web dashboards (`web/frps/`, `web/frpc/`)
`make clean`	Remove `bin/`, `lastversion/`, `.cache/`, `.compat/`

Build tags: frps, frpc, and noweb (auto-added when web assets missing).
CGO disabled, -trimpath, stripped symbols.

Command	What
`make test` / `make gotest`	Unit tests with `--cover` per package
`make e2e`	E2E via ginkgo (parallel, 16 nodes)
`make e2e-trace`	Same with `LOG_LEVEL=trace`
`make alltest`	`vet → gotest → e2e` (CI pipeline)

E2E uses Ginkgo/Gomega. Requires ginkgo binary (auto-installed by hack/run-e2e.sh).
Binary paths: FRPC_PATH / FRPS_PATH env vars (default bin/frpc, bin/frps).
E2E mock servers in test/e2e/mock/.
Compatibility e2e: make e2e-compatibility, make e2e-compatibility-smoke, make e2e-compatibility-floor. Controls: FRP_COMPAT_BASELINE_COUNT (default 8), FRP_COMPAT_FLOOR_VERSION (default 0.61.0).
CI: CircleCI runs make alltest after building web assets.

Command	What
`make fmt`	`go fmt ./...`
`make fmt-more`	`gofumpt`
`make gci`	Import organizer: standard → default → `github.com/fatedier/frp/`
`make vet`	`go vet` with `noweb` build tag
`golangci-lint run`	Full lint (v2 config, `.golangci.yml`)

Config: TOML, YAML, or JSON. INI format is deprecated (v0.52.0+). Default: ./frpc.ini.
DB-first config: frps stores config in SQLite by default. Config file is optional (-c flag bypasses DB).
First-run flow: No config file + no DB config → auto-saves defaults (bind 0.0.0.0:7000, web 0.0.0.0:7500) and redirects admin UI to setup wizard.
Flags: --config / -c, --strict_config (default true), --allow-unsafe.
Feature gates: Enabled via featureGates = { VirtualNet = true }.
Store: store.path enables dynamic proxy CRUD at runtime (persisted to disk, takes precedence over static config on name conflict).
Config aggregation: Static file + includes + store. start acts as global allowlist (not recommended for new configs; prefer per-proxy enabled).
frpc subcommands: frpc reload, frpc verify, frpc status, frpc tcp (direct CLI proxy creation).
Multi-client mode: --config_dir runs one frpc per config file (testing only, not stable).
Admin DB: SQLite via ent ORM at pkg/db/. Schema: User, FrpcClient, Proxy, ServerConfig. Auto-creates admin.db and seeds default admin user (admin/admin123).
Admin UI: htmx-based dashboard at /admin/ on frps web server port. Login required, session cookie auth. Pages: Dashboard, Clients, Proxies, Settings.
Server Config via UI: All frps settings editable from Settings page. First-run redirects to setup wizard. Save triggers restart prompt.

See doc/agents/release.md for the full process. Key steps: