Development Setup¶

Prerequisites¶

Go 1.24+
golangci-lint 2.10.1+
mise (recommended for tool management)

Getting Started¶

git clone https://github.com/charliek/shed-extensions.git
cd shed-extensions
mise install        # installs Go and golangci-lint
make check          # runs lint + tests

Building¶

make build          # build all binaries
make build-host     # build shed-host-agent (macOS)
make build-guest    # cross-compile guest binaries (Linux amd64 + arm64)

Testing¶

make test           # run all unit tests
make coverage       # tests with HTML coverage report

Linting¶

make lint           # run golangci-lint
make fmt            # format code with gofmt
make check          # lint + test together

Documentation¶

Docs use MkDocs Material. Requires uv for Python dependency management.

make docs-serve     # serve at http://127.0.0.1:7071
make docs           # build to site-build/

Docker Image (Guest Artifacts)¶

Guest binaries are distributed as a multi-arch Docker image consumed by shed's VM Dockerfiles. To build and test locally:

# Build for local arch (linux/arm64 on ARM Mac, linux/amd64 on x86 Linux)
docker buildx build -t ghcr.io/charliek/shed-extensions:dev --load .

# Verify contents
cid=$(docker create --entrypoint=/ ghcr.io/charliek/shed-extensions:dev)
docker export "$cid" | tar tf - | grep shed-
docker rm "$cid"

# Test with shed's image build (in the shed repo)
cd ~/projects/shed
./scripts/build-vz-rootfs.sh --variant experimental --shed-ext-version dev

The release workflow (.github/workflows/release.yaml) builds and pushes the multi-arch image to ghcr.io/charliek/shed-extensions:<tag> on every git tag, alongside the GoReleaser host binary release.

Manual Testing¶

For end-to-end testing against a running shed:

Start shed-server: shed-server serve
Start host agent: go run ./cmd/shed-host-agent --config ~/.config/shed/extensions.yaml
Create a shed with the experimental image: shed create test --image experimental
Inside the shed: ssh -T git@github.com