Development and contributing

This repo is source-first. Keep implementation changes small, tested, and separate from docs-only changes where practical.

Repository layout

Path	Purpose
cmd/mytunnel	Client CLI.
cmd/mytunneld	Edge daemon and control commands.
internal/client	SSH control-plane and reverse tunnel helpers.
internal/edge	Lease store, slug policy, Caddy route management, and daemon service logic.
deploy	systemd, Caddy, and SSH forced-command assets.
scripts	Install, upgrade, check, uninstall, and validation workflows.
docs-site	Public Starlight documentation site.

Build

make build

Verify implementation

Primary local verification:

go test ./...
go vet ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
shellcheck \
  deploy/ssh/mytunnel-ssh-gate.sh \
  scripts/bootstrap-edge.sh \
  scripts/check-client.sh \
  scripts/check-edge.sh \
  scripts/install-client.sh \
  scripts/install-edge.sh \
  scripts/install-edge-ssh-key.sh \
  scripts/install-local.sh \
  scripts/real-system-validation.sh \
  scripts/test-ssh-gate.sh \
  scripts/uninstall-edge.sh \
  scripts/uninstall-local.sh \
  scripts/upgrade-edge.sh \
  scripts/upgrade-local.sh

Docker fallback:

make verify-docker

Release-quality verification:

go test -race ./...
go test ./... -count=1
go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
make build
make release-client
make checksums

Verify docs

From the docs site:

cd docs-site
npm install
npm run check

Run the local docs server:

cd docs-site
npm run dev

Preview a production build:

cd docs-site
npm run build
npm run preview

Docs checks include:

• Prettier formatting.
• Markdownlint.
• cspell.
• Command-example classification markers.
• Starlight build and internal link validation.

Command example markers

Every shell command block in public docs should be classified with one of these invisible comments immediately before the block:

<!-- docs-check: local -->
<!-- docs-check: docker -->
<!-- docs-check: edge-only -->
<!-- docs-check: example-only -->
<!-- docs-check: output-only -->

Use:

• local for commands that can run on a normal checkout.
• docker for commands intended to run through Docker verification.
• edge-only for commands that require root, systemd, an edge host, DNS, SSH credentials, or public traffic.
• example-only for illustrative command shapes that include placeholders or should not be run directly.
• output-only for shell-shaped output blocks.

Contribution expectations

• Preserve user dirty work.
• Keep implementation changes scoped.
• Treat the edge daemon as the security boundary.
• Do not trust client flags for owner identity or privilege.
• Keep SSH control commands and long-running tunnel processes separate.
• Use strict shell mode and quote variables in scripts.
• Avoid leaking secrets in logs and docs.
• Add tests for security-sensitive behavior.

Public release checklist

• Choose and add a real LICENSE.
• Run release-quality verification.
• Run scripts/real-system-validation.sh against a real edge host.
• Confirm Caddy Admin API is not externally reachable.
• Confirm wildcard DNS and TLS issuance with the real provider.
• Confirm upgrade rollback on a real edge host.