Build¶

How to build the AutonomyOps ADK from source and run unit tests.

1. Clone the Repository¶

git clone https://github.com/autonomyops/adk.git
cd adk

2. Build the CLI Binary¶

make build

Expected output:

==> built: bin/autonomy

The autonomy binary is the unified CLI for all ADK operations: policy management, OCI artifact signing/verification, telemetry drain, runtime start, lock fingerprinting, and more.

3. Verify the Binary¶

./bin/autonomy --help

This prints the top-level command list. All subcommands follow the pattern autonomy <noun> <verb> (e.g., autonomy policy build, autonomy oci attach-lock).

4. Run Unit Tests¶

make test

This runs all unit tests across all Go modules in the workspace. Integration tests (gated with //go:build integration) and FI tests (//go:build fi or //go:build integration in edge/fi/) are excluded.

5. Run Go Linter¶

make lint-go

The linter configuration is in .golangci.yml at the repo root.

6. Build the Documentation Site¶

Requires Python 3.12 and the packages in docs/requirements-sphinx.txt:

pip install -r docs/requirements-sphinx.txt
make docs

The built site is written to docs/_sphinx_build/html/. To serve locally:

make docs-serve

Browse to http://localhost:8000.

Per-Module Build and Test¶

The repo uses a Go workspace (go.work). To build or test a specific module in isolation (without the workspace, for dependency hygiene):

cd runtime
GOWORK=off go build ./...
GOWORK=off go test ./... -v -count=1

Module	Test command
`lock`	`cd lock && GOWORK=off go test ./...`
`runtime`	`cd runtime && GOWORK=off go test ./...`
`policy`	`cd policy && GOWORK=off go test ./...`
`oci`	`cd oci && GOWORK=off go test ./...` (integration: add `-tags integration`)
`telemetry`	`cd telemetry && GOWORK=off go test ./...`
`orchestrator`	`cd orchestrator && GOWORK=off go test ./...`
`edge`	`make edge-test`
`cmd/autonomy`	`cd cmd/autonomy && GOWORK=off go test ./...`

For the edge FI harness:

make edge-fi-go    # Go integration tests (requires Docker for registry)
make edge-fi-shell # Shell FI tests (some require root/CAP_NET_ADMIN — others skip)

Troubleshooting¶

go: no go.mod file found at the repo root: There is no go.mod at the repo root — only a go.work workspace. Run go commands from a module directory with GOWORK=off, or use go build ./... from the root (reads go.work), or use make build.

go mod tidy hits VCS: Each cross-referencing go.mod requires a replace directive pointing to the local path. Run GOWORK=off go mod tidy from the specific module directory.

3-part go version rejected in go.mod: Use 2-part go 1.N in all go.mod files — no patch version suffix, no toolchain directive. The workspace toolchain is set once in go.work (toolchain go1.25.9) and propagates to all modules automatically; per-module toolchain directives would conflict with it.

Do Not Do¶

❌ Do NOT run go build ./... from the repo root expecting a single binary — use make build or build from individual module directories
❌ Do NOT add toolchain directives to individual go.mod files — the workspace toolchain in go.work is authoritative
❌ Do NOT commit go.sum changes without running GOWORK=off go mod tidy in the affected module