Development / Building from Source
This page covers building connect from source and the local dev workflow. For adding a new tunnel type or
management Extension in your fork, see Extension Authoring — this page only covers
the surrounding build/test/verify loop, not how to write the extension itself.
Prerequisites
- Go (version per
go.mod, currently 1.27+) uv— only needed if you're also building the documentation site locally (see Documentation below)openssl,yamllint,shellcheck,golangci-lint,gosec,gograph— used bymake lint/make verify; not required just to build the binary
Build
git clone https://github.com/dioad/connect.git
cd connect
go generate ./...
go build .
go generate ./... builds the embedded management-UI web assets (Vite/React, under web/ and the mail
management UIs) — required before go build . will produce a working binary with a functional management UI.
Test
go test -race ./...
make verify
The full pre-completion check, run in CI and expected before any change is considered done:
make verify
This runs, in order:
go fmt/go fix/golangci-lint run/gosec/go vet— linting and static analysis.yamllintover the example agent/server configs andshellcheckover the test scripts.gograph boundaries— checks package imports against the layers inboundaries.json.go test -race ./...— the full test suite, race detector enabled.go generate ./...+go build .— the same build as above.bash test-scripts/smoke_test_local.sh— starts a real agent and server locally against generated test certificates and exercises reverse/forward tunnels, DNS, and the management API end to end.
Local test certificates
The local smoke test and several manual testing flows need a local CA and leaf certificates:
make test-certificates
Generates a server and client CA plus leaf certificates under .local-dev/ (gitignored). Re-run if you need fresh
certificates; existing ones aren't regenerated once present (see the Makefile's file-based targets).
Documentation site
The contents of doc/ are built into two mkdocs-material sites — this usage site, and a separate Architecture
site covering internals/C4 models (linked from the home page). Building them locally:
make docs-serve # usage site, http://127.0.0.1:8000
make docs-serve-architecture # architecture site, http://127.0.0.1:8001
Both regenerate the CLI reference (internal/tools/gendocs) and run uv sync first. make docs builds both
statically (same --strict checks CI runs) into site/ (gitignored).
Adding a custom tunnel type
If you fork and compile the agent yourself, internal/cmd/agent/registry_init.go is where built-in tunnel types
are registered — see Extension Authoring § Register the Tunnel Type for the full
walkthrough (defining a config struct, implementing a ServerType, and registering it).