Skip to content

Getting Started

Want to get up and running as quickly as possible to see what all the fuss is about? Use our bootstrap scripts! Follow our Quick Start to get started!

Quick Start

1. Download and initialize the CLI

Install the CLI on your development machine with the correct command for your architecture:

curl -L > grlx && chmod +x grlx
./grlx init

You’ll be asked some questions, such as which interface the farmer is listening on, and which ports to use for communication. Set the interface to the domain name or IP address of the farmer.

If you plan to install the farmer on k3s (see below), then use the IP address of your k3s server, API port 30405, and Bus port 30406. If you plan to locally run the Docker Compose file below, then all of the defaults are good (localhost and default ports).

Once configured, the CLI prints out your administrator public key, which you’ll need for the next step! It’s recommended you now add grlx somewhere in your $PATH.

2. Install the farmer on the management server

You will then need to install the farmer on the management server. The farmer is the central server that manages the fleet.

# or, just run as root instead of sudo
curl -L | sudo bash

You’ll be asked several questions about the interface to listen on, which ports to use, etc. For the quick start, it’s recommended to use the default ports (TCP 5405-5406). You’ll be prompted for an admin public key, which you should have gotten from the prior step, and a certificate host name(s). Make sure the certificate host name matches the external-facing interface (a domain or IP address) as it will be used for TLS validation!

3. Install the sprout on every node you want to manage

The sprout is the agent that runs on every node you want to manage. It’s responsible for executing commands and reporting back to the farmer.

# Be sure to change FARMERINTERFACE to the domain or IP address of the farmer.
# FARMERBUSPORT and FARMERAPIPORT variables are available in case you need
# to use different ports (see k3s note below).
curl -L | FARMERINTERFACE=localhost sudo -E bash

NOTE: If you deployed the k3s farmer above, then use:

# Be sure to change FARMERINTERFACE to the domain or IP address of the farmer.
curl -L | FARMERBUSPORT=30406 FARMERAPIPORT=30405 FARMERINTERFACE=localhost sudo -E bash

Once the sprout is up and running, return to the CLI.

4. Accept the TLS cert and the sprout keys

Next, you must accept each sprout’s public key and the farmer’s TLS certificate. This is done using the keys command. Furthermore, using grlx version, shows you that you are able to connect to your farmer.

# You will be asked to download and trust the TLS certificate for
# the farmer, choose Y.
grlx version
grlx keys accept -A

5. Now you are ready to cook!

grlx -T \* test ping
grlx -T \* cmd run whoami
grlx -T \* cmd run --out json -- uname -a


If you ever need to uninstall the grlx-farmer, you can do so with the following commands:

curl -L | UNINSTALL=true sudo -E bash

Or the grlx-sprout:

curl -L | UNINSTALL=true sudo -E bash