Contributing
Local development
Prerequisites, make targets, the debug stack, and running tests.
Prerequisites
- Go —
go.modpins the Go language version and exact toolchain. Use those values rather than a separately maintained version list. - Bun — CI pins the version in
.github/workflows/ci.yml. Use that same version forweb/,desktop/,sdk/, andautomations/.
Make targets
The root Makefile covers the Go binaries and the web build:
make build # build-cli + build-server + build-runner + build-web
make build-cli # ./dist/nexul, the install and upgrade command
make build-server # ./dist/nexul-server, without the web UI
make build-runner # ./dist/nexul-runner
make build-web # bun run --cwd web build
make build-single # ./dist/nexul-server as released, web UI embedded via go:embed
make test # go test ./...
make vet # go vet ./...
make lint # golangci-lint
make vuln # govulncheck
make coverage # go test -race with the 80% gate
make sqlc # regenerate sqlcgen from internal/platform/storage/queries/*.sql
make sqlc-check # sqlc vet + sqlc diff — fails if generated code is stale
make live-topics # rewrite the web's copy of the topics the live socket pushes
make event-schemas # regenerate the event contract and the SDK's event types
make permission-catalog # rewrite the clients' copy of the permission catalog and of each route's permissionThe automations host binaries come from Bun, not the Makefile:
bun run --cwd automations build:binaries writes
automations/dist/nexul-automations-<os>-<arch>[.exe] for every release
target.
Running the server and the web dev server
Outside the debug stack, run the server directly against Go:
go run ./server/cmdThe server generates its auth secret and reads its config from environment
variables (see .env.example — nothing is required for a local run; every
variable there is an override). It listens on :8080 unless
NEXUL_HTTP_ADDR says otherwise.
Trying the installer
nexul install downloads every binary from a release, checked against its
checksums.txt. To try it against binaries you built, serve a directory laid
out like a release (<tag>/<binary>-<os>-<arch> plus <tag>/checksums.txt)
and point the installer at it with NEXUL_RELEASE_URL, passing the tag with
--version. Do this on a disposable machine or VM: the install creates
services and a system user.
The web app has its own dev server:
bun install
bun run --cwd web devThe debug compose stack
The debug stack is for developing Nexul only; releases ship no images, and a
real install runs every component as a native service.
docker-compose.debug.yml runs the server, web (Vite, not nginx), runner,
automations host, and an OpenObserve instance for logs together, with Delve
attached to the Go binaries (:2345 server, :2346 runner):
docker compose -f docker-compose.debug.yml upWeb (:5173), the server (:8080: the API, MCP at /mcp, and the runner WebSocket at /ws/runner), and
OpenObserve (:5080) are all reachable on the host.
Named node_modules volumes. web-node-modules and
automations-node-modules are named Docker volumes, not bind mounts —
they exist so the container’s installed dependencies don’t get shadowed by
whatever (or nothing) is in your host checkout’s node_modules. That means
a host-side bun install doesn’t reach the container: after changing
package.json in web/ or automations/, install inside the running
container instead:
docker compose -f docker-compose.debug.yml exec web bun install
docker compose -f docker-compose.debug.yml exec automations bun installNever run docker compose -f docker-compose.debug.yml down -v to pick up a
dependency change — that also wipes the debug database and OpenObserve
volumes. exec ... bun install is the fix; down -v is not.
Pairing a computer locally
A computer pairs through its personal runner, so a local or end-to-end check
runs one by hand against the debug stack or a local server, reaching a
throwaway T3 Code so your own stays untouched. Keep the scratch files in a
git-excluded folder such as .verify/.
-
Start a throwaway T3 Code in a base directory of its own, on a port of its own, and give it a project:
t3 serve --base-dir "$PWD/.verify/t3home" --port 47190 --host 127.0.0.1 --no-browser t3 project add --base-dir "$PWD/.verify/t3home" <a git folder>Any T3 Code build works: a release’s AppImage, extracted with
--appimage-extract, runs asELECTRON_RUN_AS_NODE=1 squashfs-root/t3code squashfs-root/resources/app.asar/apps/server/dist/bin.mjs. Put a smallt3script that runs that command first onPATH, because the runner mints its pairing token with the firstt3it finds. -
Add a computer as yourself: press Add a computer in Your settings → Computers and keep the dialog open to watch its checks (the token is the command’s last word), or
POST /api/pairing/computers/enrollmentswith{}, which returns the computer and itstoken. -
Trade the token for the runner’s credential and save it to a file:
curl -s -X POST http://127.0.0.1:8080/api/runners/enroll \ -H 'Content-Type: application/json' \ -d '{"token":"<token>","machine":"'"$(hostname)"'","os":"linux","arch":"amd64"}'The answer holds
nameandcredential; the credential is shown once. -
Run the runner in personal mode, pointed at the throwaway’s base directory:
NEXUL_SERVER_URL=http://127.0.0.1:8080 NEXUL_CREDENTIAL_FILE=.verify/credential \ NEXUL_RUNNER_MODE=personal NEXUL_RUNNER_NAME=<name> T3CODE_HOME="$PWD/.verify/t3home" \ go run ./runner/cmdA runner with a custom
T3CODE_HOMEreads the throwaway’s port from its runtime file and never falls back to 3773, so once the throwaway stops, its dials are refused instead of reaching your own T3 Code.
Within seconds the runner reports T3 Code answering and the computer pairs
on its own: GET /api/pairing/computers shows a token_expires_at, or
pair_error saying why it could not. POST /api/pairing/computers/{id}/pair
with no body pairs it again now. Stop each process by the PID you started it
with.
Running tests
go test ./... # Go, all packages
bun run --cwd web test # web and client-core, Vitest
bun run --cwd native test # phone app, Jest
bun run --cwd desktop test # desktop, Vitest
bun run --cwd sdk test # sdk, bun test
bun run --cwd automations test # automations, bun testThe coverage gate
make coverage is the enforced gate, not a suggestion:
make coverageIt runs go test -race with a coverage profile over every package but
internal/platform/storage, whose tests run without -race because the
detector makes the pure-Go SQLite engine about 25 times slower; the
server/cmd integration tests still drive storage under -race. The
Makefile filters cmd/*, testutil/, sqlcgen/, and t3rpctest/ from the
profile, computes the percentage over the remaining statements, and fails
below 80%.
It writes coverage.filtered.out and coverage.html, the same artifacts CI
uploads. See
Coding standards for what the gate
expects beyond the number.