Development Environment Setup

Prerequisites

Go

The module requires Go 1.26.4 or later. The exact version is pinned in go.mod at the repo root. The CI workflows use actions/setup-go with go-version-file: go.mod, so the version is always read from that file — follow the same practice locally.

go version   # should report go1.26.4 or later

System Dependencies

macOS

The CLI uses CoreBluetooth for BLE device discovery. CGO must be enabled when building on macOS (it is enabled by default):

# If you have explicitly disabled CGO, re-enable it
export CGO_ENABLED=1

No additional system packages are needed on macOS for a standard CLI build.

Swiftly and the clang shim

If Swiftly is installed, its clang shim (~/.swiftly/bin/clang) often appears ahead of /usr/bin on PATH. The shim refuses to run when the repository's .swift-version does not match an installed Swift toolchain, causing cgo builds to fail with an opaque exit status 2 and no output.

The go/Makefile works around this by setting CC ?= /usr/bin/clang on Darwin so Go's cgo toolchain falls back to Apple's real clang whenever CC isn't already set. This is applied automatically when you use any make target. If you invoke go build directly (not via make), set the variable yourself:

export CC=/usr/bin/clang

Linux

The audio subsystem uses ALSA. Install the development headers before running tests or building the agent:

# Debian / Ubuntu
sudo apt-get install -y libasound2-dev libusb-1.0-0-dev pkg-config

# Fedora / RHEL
sudo dnf install -y alsa-lib-devel libusb1-devel pkgconf-pkg-config

libusb-1.0-0-dev and pkg-config are required by the CLI's CGO dependency (USB recovery flashing via gousb) and by the SBOM integration test (scripts/test/generate-sbom.integration.sh), which builds wendy with CGO_ENABLED=1.

Windows

No additional system packages are required for a standard CLI build on Windows.

Some local setup scripts are unsigned, so Windows may block them even when you trust the repository. If you need to run a local, trusted PowerShell setup script, use a one-time bypass only after reviewing the script:

Get-Content .\set-up-windows.ps1
powershell -ExecutionPolicy Bypass -File .\set-up-windows.ps1

The bypass applies only to that PowerShell invocation. Run it from a non-elevated (standard-user) PowerShell window. If a specific step fails with an access-denied error, review that section of the script before re-running as Administrator.

Additional Tools

Environment Variables

Local .env* files are ignored by git, while .env.example files may be committed as templates. Do not commit real credentials.

For screencast voiceover variables, use screencast/.env.example and see screencast tooling.

Cloning

git clone https://github.com/wendylabsinc/wendy-agent.git
cd wendy-agent

All Go code lives under go/. Run every make target and go command from that directory (or use the make targets which set the working directory automatically).

Building

The Makefile lives in go/. All targets below are run from go/.

Build both binaries (native architecture)

cd go
make build
# Produces: bin/wendy bin/wendy-agent

Note: On Windows, only the CLI builds (bin/wendy.exe) because wendy-agent does not have Windows support.

Build just the CLI

make build-cli   # bin/wendy on Unix, bin/wendy.exe on Windows

On Windows, make build-cli invokes PowerShell for the native Windows CLI build.

Build just the agent

make build-agent   # bin/wendy-agent

Note: build-agent is not supported on Windows. Run this target on macOS, Linux, or WSL.

Cross-compile

The Makefile contains pre-wired targets for every supported platform. All cross-compiled targets use CGO_ENABLED=0:

make build-agent-linux-amd64    # bin/wendy-agent-linux-amd64
make build-agent-linux-arm64    # bin/wendy-agent-linux-arm64
make build-cli-darwin-arm64     # bin/wendy-darwin-arm64
make build-cli-windows-amd64    # bin/wendy-windows-amd64.exe
make build-all                  # all of the above in one shot

Note: macOS CLI builds in CI run on a macOS runner (macos-15) with CGO_ENABLED=1 because CoreBluetooth is required for BLE support.

Version embedding

The build embeds the version string via ldflags:

VERSION=1.2.3 make build-cli
# equivalent to:
go build -ldflags "-s -w -X github.com/wendylabsinc/wendy/go/internal/shared/version.Version=1.2.3" ./cmd/wendy

A dev version is embedded when VERSION is not set.

Running locally without overwriting your installed binaries

CLI

Add a shell alias so you can iterate on CLI changes without touching your installed wendy:

# ~/.zshrc or ~/.bashrc
wendy-dev() {
  (cd /path/to/wendy-agent/go && go run ./cmd/wendy "$@")
}

Use it wherever you'd use wendy:

wendy-dev discover --json
wendy-dev run

Agent

wendy-agent-dev() {
  (cd /path/to/wendy-agent/go && go run ./cmd/wendy-agent "$@")
}

Installing locally

cd go
make install
# installs both binaries to $(go env GOPATH)/bin

Note: make install is not supported on Windows because wendy-agent does not have a Windows build yet. Run this target on macOS, Linux, or WSL.

Regenerating Protobuf Code

The generated code under go/proto/gen/ must not be edited by hand. To regenerate after changing a .proto file:

1. Install the required plugins:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

2. Run the generation script:

cd go
make proto
# runs scripts/generate-proto.sh

The script reads .proto sources from proto-defs/ at the repo root and writes generated Go files to go/proto/gen/ under three packages: agentpb, agentpb/v2, and cloudpb. OpenTelemetry protos are not generated here — they map to the upstream go.opentelemetry.io/proto/otlp/... packages.

Device Setup (for running the agent locally)

The agent manages containers via containerd. On a Debian/Ubuntu machine:

sudo apt install containerd
sudo systemctl start containerd
sudo systemctl enable containerd

Then run the agent with:

sudo ./bin/wendy-agent

The agent listens on port 50051 (plaintext, pre-provisioning) and port 50052 (mTLS, post-provisioning). It also serves a local unix socket at /run/wendy/agent.sock for on-device containers with the admin entitlement. The OTEL collector listens on 4317 (gRPC) and 4318 (HTTP). All ports can be overridden via environment variables — see debugging.md.

Dependency License Checks

The repo tracks a committed baseline of dependency licenses:

make licenses          # verify current deps match licenses.csv
make licenses-update   # regenerate licenses.csv after adding a dependency

Run make licenses before opening a PR if you added or upgraded dependencies.