Skip to main content

Runners

Runners in the sidebar (/workflows/runners) lets you run workflow nodes on your own machine — a server, a VM or a laptop. The page is subtitled Run workflow nodes on your own machines.

FluidGrids keeps running the workflow: triggers, the run engine, the run history and logs, and passing data between nodes. A node you set to Run on a runner executes on that machine, inside a local sandbox, and its result comes back to FluidGrids. Use a runner when a node needs to reach something inside your network — a database, an internal API — or should run on your own hardware, for example so that its outbound requests come from your machine's IP address.

By default a node on a runner reaches the public internet only. You open the private destinations it may reach on the runner machine — see Reach your private network.

The runner only makes an outbound connection (HTTPS/WebSocket on port 443). Nothing on your machine listens for incoming connections.

The Runners sidebar entry is shown by default to the Automation Owner and Automation Lead roles. See Roles and Permissions.

Add a runner​

  1. Open Runners and click Add runner.

  2. Enter a Name (for example build-server or my-laptop) and click Create runner.

  3. The dialog shows two things: an install command and the runner token. Run the command on the machine that should run your nodes (add sudo before sh to install as root, which the gVisor sandbox needs):

    curl -fsSL https://www.fluidgrids.ai/downloads/runner/install.sh | sh

  4. When the installer asks Runner token from FluidGrids → Runners, paste the token. What you type is hidden.

    The token is never part of the command, so it does not end up in your shell history or in the list of running processes that other users on the machine can see. It is shown only once — if you lose it, use Rotate token to get a new one.

  5. The dialog shows Waiting for the runner to connect… and switches to Connected within a few seconds of the runner starting. Click Done.

Installing without a terminal​

For unattended installs (cloud-init, Ansible, a CI job), write the token to a file only root can read, and pass --token-file:

curl -fsSL https://www.fluidgrids.ai/downloads/runner/install.sh | sudo sh -s -- --token-file /root/fgr-token

Without a terminal and without a token file, the installer stops and says how to pass the token. It also reads FLUIDGRIDS_RUNNER_TOKEN, but sudo drops that variable unless you pass --preserve-env=FLUIDGRIDS_RUNNER_TOKEN — and never write sudo FLUIDGRIDS_RUNNER_TOKEN=fgr_… sh, which puts the token on sudo's command line. The old --token fgr_… option still works but prints a warning, because it exposes the token.

The installer downloads the runner and checks its checksum. It then installs the sandbox technology the machine supports, checks that the machine can run nodes, and starts the runner as a background service (systemd on Linux, launchd on macOS).

Supported machines​

MachineSandboxNotes
Linux with KVM (most servers and desktops)microsandbox — a small virtual machine per nodeStrongest isolation. A non-root user must be in the kvm group.
Mac with Apple siliconmicrosandbox
Linux without KVM (most cloud VMs)Docker + gVisorRun the installer with sudo; Docker must be installed. On Debian/Ubuntu the installer adds gVisor for you.
Windows, Intel MacNot supported

A runner never runs a node outside a sandbox. If the machine has no usable sandbox, the installer stops and says why.

The runner list​

Each runner shows its Name, Status, Machine (host name and OS/architecture it reported), Sandbox (microsandbox or gVisor), Private network and Last seen.

Private network shows what that runner's nodes may reach besides the public internet: Public internet only, or each opened destination with its ports and the node types it is limited to. It is read-only here — it is set on the runner machine.

StatusMeaning
OnlineConnected now. Nodes can run on it.
OfflineIt has connected before but is not connected now (machine off, service stopped, network down).
Not connected yetCreated, but the runner has never connected with its token.

Actions:

  • Rotate token — issues a new token. The old one stops working at once and the runner is disconnected. Run the install command again on that machine and paste the new token when it asks. Your private-network rules are kept.
  • Remove — disconnects the runner and its token stops working. Nodes set to run on it fail until you pick another runner or FluidGrids Cloud.

Run a node on your runner​

  1. Open the workflow in the builder and double-click the node to open the full node editor.
  2. Open the Settings tab.
  3. Under Run on, pick your runner instead of FluidGrids Cloud (default).
  4. Save the workflow.

In the list, a runner that is not online is marked (Offline) or (Not connected yet). If the runner a node was set to has since been removed, the selector shows Removed runner.

Run on applies to app nodes from the Node Store — and to the AI Agent's chat model, memory and tool nodes. Built-in nodes (IF, Switch, Merge, Code, the built-in HTTP Request and other Node Blocks) and triggers always run in FluidGrids, even though their Settings tab also shows Run on.

If the runner is offline, the node fails​

An app node set to a runner runs there or not at all. If the runner is offline, or the setting no longer points at a valid runner, the node fails with a message that says so. It never falls back to FluidGrids Cloud, because that would run it somewhere you did not choose. The error appears on the run in Runs like any other node failure. Use the node's error settings (for example continue or an error branch) if the rest of the workflow should carry on.

A runner runs a limited number of nodes at the same time (4 by default). Extra nodes wait briefly for a free slot rather than failing.

Reach your private network​

A node can reach a private address only if you opened it on the runner machine. Run these on the machine (use sudo if the runner was installed as root, so they edit /etc/fluidgrids-runner/config.json):

# A PostgreSQL server, for the PostgreSQL node only
sudo fluidgrids-runner network allow 10.0.5.12 --port 5432 --node store/postgresql

# An internal API by name, a port range, every node
sudo fluidgrids-runner network allow api.corp.internal --port 8000-8100

sudo fluidgrids-runner network list
sudo fluidgrids-runner network remove 2        # by number, or by destination
  • Destination — a private IPv4 address, an IPv4 range such as 10.0.8.0/24 (no wider than /8), or a hostname. Hostnames are resolved by the machine's own DNS and /etc/hosts, so internal names work.
  • Ports — --port takes TCP ports and ranges (5432, 443,8443, 8000-8100); --any-port opens every TCP port.
  • Nodes — --node limits the rule to node types, such as store/postgresql or store/http-tool. Without it, every node on this runner can reach the destination, so scope rules to the nodes that need them.
  • Applies within seconds — the next node that starts picks up the change; there is no restart. A node already running keeps the access it started with. The Private network column on this page updates too.
  • Never openable — the cloud metadata service and the rest of 169.254.0.0/16, loopback, and 172.31.248.0/21 (the runner's own sandbox addresses). Only IPv4 destinations can be opened.
  • The machine itself — opening this machine's own address (or a range that includes it) lets nodes reach its services on those ports. Open exact addresses and ports where you can.

The list lives only in the runner's config file. FluidGrids shows it but cannot change it: nobody can open a path into your network from a FluidGrids account. Everything else stays blocked — other private addresses, other ports, the host, and other nodes.

If a node gets Connection refused or a timeout reaching a private address, first check that the destination, port and node type are opened on that runner (sudo fluidgrids-runner network list on the machine). If they are, check that the service is listening on that port and that no firewall between the runner and the service blocks it.

What reaches your machine​

  • The node's image, downloaded with a short-lived pass that can read that one node's image and nothing else.
  • The node's input, and the credentials that node uses — for example the OAuth token of the connection it is set to. The node needs them to do its work.

The node's result goes back to FluidGrids, and data passed between nodes goes through FluidGrids — a runner does not keep a workflow's data on your machine. Inside its sandbox, a node can reach the public internet and the private destinations you opened for it. It cannot reach anything else on your network, your cloud provider's metadata service, the host machine (unless you opened its address), or other nodes.

Runner commands​

The installer sets everything up. These commands are for checking on or changing a runner:

fluidgrids-runner doctor            # can this machine run nodes? (also lists open private destinations)
fluidgrids-runner network list|allow|remove   # private network access, see above
fluidgrids-runner run               # run in the foreground (for debugging)
fluidgrids-runner register [--token-file <path>] [--capacity 4] [--driver auto|microsandbox|gvisor]   # asks for the token
fluidgrids-runner install-service   # start on boot (systemd / launchd)
fluidgrids-runner uninstall-service
fluidgrids-runner version

The configuration is stored at /etc/fluidgrids-runner/config.json (when installed as root) or ~/.config/fluidgrids-runner/config.json, readable only by its owner. To keep the token off disk, set FLUIDGRIDS_RUNNER_TOKEN in the service environment instead.

To uninstall, run fluidgrids-runner uninstall-service on the machine and Remove the runner on this page.

Troubleshooting​

The Run on list only shows FluidGrids Cloud. — The workspace has no runners yet. Add one on this page, then close and reopen the node editor.

The runner stays "Not connected yet". — The install command did not finish, or the machine cannot reach graphqlworkspaces.burdenoff.com on port 443. Run fluidgrids-runner doctor on the machine and check the service log: journalctl -u fluidgrids-runner on Linux (journalctl --user -u fluidgrids-runner if you installed without root). On macOS the service is the LaunchAgent ai.fluidgrids.runner.

A runner went "Offline". — The machine is off, the service stopped, or the network dropped. The runner reconnects by itself when it can. If you rotated the token, run the install command again and paste the new token.

"This node is set to run on a self-hosted runner, but no valid runner is selected." — The node's Run on points at nothing usable. Pick a runner, or FluidGrids Cloud, in the node's Settings.

"Runner is offline" / "The runner for this node is offline". — Start the runner, or switch the node to another runner or to FluidGrids Cloud.

"Connection refused" or a timeout reaching a private address. — Usually the destination is not opened for this node on the runner: on the machine, run sudo fluidgrids-runner network list and add it with network allow (with --node and this node's type), then run the workflow again. If the rule is there, the service may not be listening on that port, or a firewall between the runner and the service may block it.

network allow worked, but nothing changed. — The command edited a different config file from the one the runner service uses. Run it as the same user as the service: with sudo if the runner was installed as root.

Last updated on