Skip to content

Install Gubernator (gbnt)

You must install the Gubernator CLI (gbnt) on your machine to manage clusters, interact with the API, or run the Manager daemon itself.

Choose your operating system below to download and install the pre-compiled binary.

Linux

  1. Download the latest release: 

    curl -LO "https://github.com/mario-ezquerro/gubernator/releases/latest/download/gbnt-linux-amd64"

  2. Make the gbnt binary executable: 

    chmod +x gbnt-linux-amd64

  3. Move the binary to a file location on your system PATH: 

    sudo mv gbnt-linux-amd64 /usr/local/bin/gbnt

  4. Verify the installation: 

    gbnt --help

macOS

You can download the binary depending on your Mac's processor architecture (Intel or Apple Silicon).

Apple Silicon (M1/M2/M3)

  1. Download the binary: 

    curl -LO "https://github.com/mario-ezquerro/gubernator/releases/latest/download/gbnt-darwin-arm64"

  2. Make it executable and move it to your PATH: 

    chmod +x gbnt-darwin-arm64
sudo mv gbnt-darwin-arm64 /usr/local/bin/gbnt

Intel (x86_64)

  1. Download the binary: 

    curl -LO "https://github.com/mario-ezquerro/gubernator/releases/latest/download/gbnt-darwin-amd64"

  2. Make it executable and move it to your PATH: 

    chmod +x gbnt-darwin-amd64
sudo mv gbnt-darwin-amd64 /usr/local/bin/gbnt

Windows

  1. Download the latest .exe release using PowerShell: 

    Invoke-WebRequest -Uri "https://github.com/mario-ezquerro/gubernator/releases/latest/download/gbnt-windows-amd64.exe" -OutFile "gbnt.exe"

  2. Move the gbnt.exe file to a folder of your choice (for example, C:\Program Files\Gubernator).

  3. Add the folder to your Environment Variables PATH so you can use gbnt from any terminal:

  4. Search for "Environment Variables" in the Windows Start menu.
  5. Click "Edit the system environment variables".
  6. Under the "Advanced" tab, click "Environment Variables...".
  7. Find the Path variable under "System variables", select it, and click Edit.
  8. Click New and add the path to the folder containing gbnt.exe.

  9. Click OK to save.

  10. Open a new PowerShell or Command Prompt window and verify the installation: 

    gbnt --help

Running via Docker

You can run Gubernator inside Docker using the multi-stage Dockerfile.

Build the Image

  • For the local architecture: 

    docker build -t gbnt:latest .

  • For multiple architectures (Intel, macOS, Raspberry Pi) using buildx: 

    docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t marioezquerro/gubernator:latest .

Run the Container

docker run -d \
  --name gbnt-manager \
  -p 4000:4000 \
  -p 4001:4001 \
  -p 4002:4002 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v gubernator-data:/data \
  -v gubernator-home:/root/.gbnt \
  -e GBNT_WEB=true \
  -e GBNT_WEB_USER=admin \
  -e GBNT_WEB_PASSWORD=admin \
  -e GBNT_MONITOR=true \
  -e GBNT_DNS_FORWARDERS="8.8.8.8 1.1.1.1" \
  marioezquerro/gubernator:latest serve

Important: The -v gubernator-data:/data and -v gubernator-home:/root/.gbnt volumes persist your database and configuration files. Without them, the cluster state is lost on restart.

Alternatively, run via Docker Compose: You can use the provided docker-compose.yml and .env files in the root of the repository to start the Manager API easily:

docker compose up -d

Gubernator comes with a built-in CoreDNS server and an automatic Caddy Ingress. It automatically creates internal domains (*.gbnt) and ingress domains (*.gbnt.test).

To browse to these local domains (e.g., http://hello-101.gbnt.test) directly from your host machine's browser without editing /etc/hosts, you can configure your OS to query Gubernator's CoreDNS.

macOS

macOS allows domain-specific DNS resolvers. Run this command once to point all .gbnt and .gbnt.test queries to Gubernator's CoreDNS (which listens locally on port 53):

sudo mkdir -p /etc/resolver
sudo sh -c 'echo "nameserver 127.0.0.1" > /etc/resolver/gbnt'
sudo sh -c 'echo "nameserver 127.0.0.1" > /etc/resolver/gbnt.test'
(Note: Do not use .local for domains on macOS, as Apple reserves it for Multicast DNS/Bonjour).

Linux (systemd-resolved)

Create a drop-in config for systemd-resolved: 

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo sh -c 'cat << EOF > /etc/systemd/resolved.conf.d/gbnt.conf
[Resolve]
DNS=127.0.0.1:5354
Domains=~gbnt ~gbnt.test
EOF'
sudo systemctl restart systemd-resolved

Run CLI Commands via Docker

To retrieve the initial tokens or see the startup logs, especially if running in detached mode (-d), you can use:

# Ver los logs de arranque
docker logs gbnt-manager

# O pedirle los tokens directamente al contenedor
docker exec -it gbnt-manager /app/gbnt legion info

Note: When you configure your local gbnt CLI using gbnt config add-context, the authentication token and server URL are stored locally on your machine in the ~/.gbntctl/config file.

Compiling from Source

If you prefer to compile Gubernator yourself, ensure you have Go 1.24+ installed. Note that CGO_ENABLED=1 is required due to the SQLite dependency.

git clone https://github.com/mario-ezquerro/gubernator.git
cd gubernator
go build -o gbnt ./cmd/gbnt
sudo mv gbnt /usr/local/bin/gbnt

Note: The Flutter Web Dashboard is pre-compiled and embedded in the internal/web/flutter/ directory. If you need to modify the dashboard UI, install Flutter SDK and run cd web-ui && flutter build web --release --base-href "/", then copy the output to internal/web/flutter/.

Post-Installation: SRE Monitoring

After installing gbnt, you can optionally deploy a full SRE observability stack with a single command:

gbnt monitor init

This deploys cAdvisor, Prometheus, Grafana, Loki, and Promtail on a dedicated Docker network. See the CLI Reference for details.