Docs

Building the Agent from Source

The agent is a single Go program in the ShellHub repository. Build it when you need an architecture we do not publish, a patched build, or reproducibility you control.

Requirements

Go, at the version pinned in agent/go.mod. Check it rather than trusting this page:

$ head -3 agent/go.mod

Build

$ git clone https://github.com/shellhub-io/shellhub.git
$ cd shellhub/agent
$ CGO_ENABLED=0 go build \
    -ldflags "-X main.AgentVersion=$(git describe --tags --abbrev=0)" \
    -o shellhub-agent .

The version has to be compiled in: the agent validates it at startup, and a binary built without it stops immediately with invalid semantic version. CGO_ENABLED=0 is what makes the result a static binary with no runtime dependencies.

Cross-compiling

Go cross-compiles without a toolchain per target:

$ export CGO_ENABLED=0 LDFLAGS="-X main.AgentVersion=$(git describe --tags --abbrev=0)"
$ GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o shellhub-agent-arm64 .
$ GOOS=linux GOARCH=arm GOARM=7 go build -ldflags "$LDFLAGS" -o shellhub-agent-armv7 .
$ GOOS=linux GOARCH=arm GOARM=6 go build -ldflags "$LDFLAGS" -o shellhub-agent-armv6 .

The published builds cover amd64, armv6, armv7, arm64 and 386.

Running it

The binary reads its configuration from the environment:

$ SHELLHUB_SERVER_ADDRESS=https://shellhub.example.com \
  SHELLHUB_PROVISIONING_KEY=<your-provisioning-key> \
  SHELLHUB_PRIVATE_KEY=/etc/shellhub.key \
  sudo -E ./shellhub-agent

For anything permanent, put it under a service manager. The standalone install shows the systemd shape.

Matching the server version

The server reports the agent version it expects at /info:

$ curl -s https://cloud.shellhub.io/info

Building from a tag matching your server avoids surprises. The agent is generally tolerant across versions, but the server does refuse public-key authentication from agents older than 0.6.0 unless SHELLHUB_ALLOW_PUBLIC_KEY_ACCESS_BELLOW_0_6_0 is set — note the spelling of that variable, the typo is real.

Where to go next

esc