Skip to main content

Connect a machine with the runner

This guide connects one machine (a laptop, a build server, a jump host) to FYAI so an agent can run tools on it. It takes about ten minutes.

You need: a FYAI project where you can create resources, and a Linux x86_64, macOS (Apple Silicon) or Windows x86_64 machine with outbound HTTPS access to catalog.fyai.co.nz. No inbound ports are needed.

1. Create the environment​

  1. Go to Platform → Environments.
  2. Select + (Add environment).
  3. Enter a Name, for example build-server-01. Leave Type as Local.
  4. Tick Install browser tools if agents should be able to drive a browser on this machine.
  5. Select Save, then select the new environment in the list.

2. Decide what it may do​

Before connecting anything, scroll to Tool Access, File Access and Approval Requirements. A new environment allows a safe default set of tools and no file paths. At minimum:

  1. Under File Access, type the directory agents should work in (for example /home/you/projects) and select Add Path.
  2. Select Save at the top of the form.

You can fine-tune the allowed tools once the runner has connected and announced them. See Control what an environment's tools can do.

3. Download the runner​

  1. In Connectivity & Deployment, under Step 2 — Set up the runner on your platform, choose your platform's tab.

  2. Select the file name to download it. Hover over the short hash beside it to see the full SHA256 if you want to check the file.

  3. Copy the file to the target machine. On Linux and macOS, make it executable:

    chmod +x fyai-runner-linux-x86_64

4. Get a registration token​

  1. Select Token at the top of the page.
  2. The Registration Token dialog shows the token and a Runner Command (Registration) for the platform tab you chose. Copy the command.

The token is reusable and expires only after 90 days without use. Treat it like a password: anyone holding it can connect a runner as this environment.

5. Start the runner​

Choose one of the following.

To try it out, run the copied command in a terminal. It runs in the foreground until you press Ctrl+C:

./fyai-runner-linux-x86_64 register --token <your-token> --url https://catalog.fyai.co.nz

To keep it running, install it as a background service instead. Use the same --token and --url, with install in place of register:

./fyai-runner-linux-x86_64 install --token <your-token> --url https://catalog.fyai.co.nz

install copies the binary to ~/.fyai/bin/, saves the token in your OS secret store, and registers a per-user service (a systemd user unit on Linux, a LaunchAgent on macOS, a Scheduled Task on Windows). It starts straight away and after every login.

On Linux, also run this once so the service keeps running when you log out and starts at boot:

sudo loginctl enable-linger $USER

On a Windows server where nobody stays logged on, add --system. The runner then runs as SYSTEM and no longer sees your user's PATH, kubeconfig or browser profile.

6. Check it's connected​

  1. Back on the environment page, the status chip changes to Running within about 10 seconds, and Last seen shows Just now.
  2. On the machine, fyai-runner status shows whether the service is installed and active, and where its logs are.

If the status stays Not Deployed, check the runner's output or log:

MessageFix
Registration token is invalid or unknownCopy the token again, or select Token for a new one.
A connection error, or nothing after "Connecting to …"The machine can't reach catalog.fyai.co.nz over HTTPS. Check DNS, firewall and proxy settings.
Another fyai-runner is already running on this machineOnly one runner can run per machine. Stop the other one (fyai-runner uninstall if it's a service).

7. Give an agent the tools​

  1. Open Build → Agents and select the agent.
  2. On the Configure tab, set Execution Environment to your environment and save.
  3. Start a new chat with the agent and ask it to do something on the machine, for example "Run git status in /home/you/projects/app".

To give every agent in a team the tools, set Execution Environment on the team instead. Agents with their own setting keep it.

Next steps​