Runner CLI and configuration reference

Reference for fyai-runner, the program that connects a machine to an execution environment. For an introduction see FYAI Runner.

In the examples, fyai-runner stands for the binary you downloaded, for example ./fyai-runner-linux-x86_64 or .\fyai-runner-windows-x86_64.exe. After install, the binary is also at ~/.fyai/bin/fyai-runner (fyai-runner.exe on Windows).

Commands

Command	Purpose
start	Connect to the platform and serve tool calls in the foreground.
register	Same as start. This is the command the environment page shows.
install	Install and start the runner as a background service.
uninstall	Stop and remove the service. Keeps the stored token.
status	Show whether the service is installed and running.
forget	Delete the stored registration token.
discover	List the tools this machine would offer.
diagnose	Check certificates, HTTPS and DNS from this machine.

Global options: --version prints the version; --help prints help for the runner or any command.

start and register

fyai-runner start [--token TOKEN] [--url URL] [--env-id ID] [--config PATH]
fyai-runner register [--token TOKEN] [--url URL] [--env-id ID] [--config PATH]

Connects to the platform and runs until stopped (Ctrl+C). Checks for an update before connecting. Fails if another runner is already running on the machine.

Option	Environment variable	Meaning
--token, -t	FYAI_REGISTRATION_TOKEN	Registration token from the environment page. Saved for later runs, so you only need it once. Without it, the saved token is used; with neither, the command fails.
--url, --catalog-url, -u	CATALOGAPIBASEURL	Platform URL to connect to. Default https://catalog.fyai.co.nz.
--env-id	FYAI_ENV_ID	Environment ID. Normally left out; the runner looks it up from the token.
--config		Path to a config file. Default ~/.fyai/runner-config.yaml.
-h, --help		Show help.

install

fyai-runner install --token TOKEN [--url URL] [--env-id ID] [--system]

Saves the token, copies the running binary to ~/.fyai/bin/, and registers and starts a per-user service that runs start at login and restarts on failure. --token can be left out if a token is already saved. --url and --env-id are written into the service definition.

OS	Service	Notes
Linux	systemd user unit ~/.config/systemd/user/fyai-runner.service	Needs systemd. Run sudo loginctl enable-linger $USER to keep it running after logout and start it at boot.
macOS	LaunchAgent ~/Library/LaunchAgents/co.nz.fyai.runner.plist
Windows	Scheduled Task FYAI Runner, triggered at logon and re-checked every 5 minutes	Runs in your interactive session.

--system (Windows only) installs the task to run as SYSTEM at boot, for servers where nobody stays logged on. The token is then stored in the task's arguments, because SYSTEM can't read your credential store, and the runner loses your PATH, kubeconfig and browser profile.

uninstall

fyai-runner uninstall

Stops and removes the service. The saved token stays; run forget to delete it as well.

status

fyai-runner status

Prints platform, installed, active, enabled, state, unit_path and logs for the installed service.

forget

fyai-runner forget

Deletes the saved registration token from the OS secret store and from ~/.fyai/credentials.

discover

fyai-runner discover [--config PATH]

Lists the tools available on this machine, marking each [OK] or [OFF] against the local allowed_tools, and lists well-known binaries on PATH that shell could use. Once connected, the environment's Tool Access setting replaces the local list, so [OFF] here doesn't mean the platform can't use the tool.

diagnose

fyai-runner diagnose

Prints the executable and certificate bundle in use and tests HTTPS and DNS from the machine (against api.github.com). Useful when the runner fails with TLS or certificate errors.

Environment variables

Variable	Meaning
FYAI_REGISTRATION_TOKEN	Same as --token.
CATALOGAPIBASEURL	Same as --url.
FYAI_ENV_ID	Same as --env-id.
FYAI_CLAUDE_BINARY	Path to the Claude Code CLI, if it isn't found automatically.
FYAI_HOME	Moves the data directory (logs, lock file, installed binary, fallback token file) away from ~/.fyai for a foreground runner. It doesn't move the config file or the secret-store entry, and installed services don't use it.

URL precedence: --url, then CATALOGAPIBASEURL, then catalog_api_url in the config file, then https://catalog.fyai.co.nz.

Configuration file

The runner reads ~/.fyai/runner-config.yaml (or the file given with --config) at start-up. Every key is optional. Restart the runner after changing it.

catalog_api_url: https://catalog.fyai.co.nz
browser:
  headless: true
  allowed_domains: [intranet.example.com]
claude:
  default_cwd: ~/projects
  allowed_permission_modes: [default, plan, acceptEdits]
  max_budget_usd: 5.0
mcp_servers:
  tickets:
    command: npx
    args: ["-y", "@acme/tickets-mcp"]
max_concurrent_tools: 8

General

Key	Default	Meaning
catalog_api_url	https://catalog.fyai.co.nz	Platform URL, when not given on the command line.
allowed_tools	kubectl, helm, git, file_read, http_local, browser, claude_code, claude_sessions, claude_status	Local allow-list. Replaced by the environment's Tool Access setting on connect.
file_allowed_paths	["*"]	Local file-path list (* = everywhere, empty = nowhere). Replaced by the environment's File Access setting on connect.
require_approval_for	[]	No effect. Set approvals on the environment.
max_concurrent_tools	8	Tool calls that may run at once.
max_tool_output_bytes	5000000	Output captured per call; anything beyond is cut off with a notice.
heartbeat_interval_s	30	WebSocket keep-alive interval.
reconnect_delay_s	5	First retry delay after a lost connection. Doubles on each failure, up to 300 seconds.
reconnect_jitter_s	2.0	Random extra delay added to each retry.
watchdog_enabled	true	Restart the process if it stops responding.
watchdog_timeout_s	90	How long it may be unresponsive before the watchdog acts.
update_check_interval_s	21600	How often to check for a new release (6 hours).
update_drain_timeout_s	120	How long to let running tool calls finish before updating.
log_file	none	Write logs to this file. Services log to ~/.fyai/logs/runner.log regardless.
mcp_retry_interval_s	30	How often an unavailable MCP server is retried.

browser

Key	Default	Meaning
headless	true	Run Chromium without a window.
profile_dir	~/.fyai/browser-profile	Persistent profile (cookies and storage survive restarts).
allowed_domains	[]	If set, the browser may only visit these hosts and their subdomains. Empty = any host.

claude

Limits for the Claude Code tools. Agents can ask for less than these, never more.

Key	Default	Meaning
binary	auto	Path to the Claude Code CLI. Auto-discovery checks FYAI_CLAUDE_BINARY, PATH and common install locations.
default_model	none	Model used when a call doesn't name one, for example sonnet.
default_effort	none	Reasoning effort when a call doesn't set one: low, medium, high, xhigh or max.
default_permission_mode	default	Mode used when a call doesn't ask for one.
allowed_permission_modes	[default, plan, acceptEdits]	Modes a call may request. The CLI's modes are default, plan, acceptEdits, auto, dontAsk and bypassPermissions.
allowed_cwds	[]	Directories runs may use. Empty = the environment's file paths.
default_cwd	none	Directory used when a call omits cwd.
default_timeout_s	270	Run time limit when the call doesn't set one. Keep under 300 for chat.
max_timeout_s	3600	Highest time limit a call may ask for.
max_budget_usd	5.0	Spend ceiling per call.
allowed_tools	none	If set, replaces the Claude Code tools a call asks for.
disallowed_tools	[]	Claude Code tools always denied, on top of the call's own list.
append_system_prompt	none	Standing instructions added to every run.
allow_config_injection	false	Whether calls may pass settings, mcp_config or agents. These can run arbitrary code, so they're refused unless you allow them.
extra_args, extra_env	[], {}	Extra CLI arguments and environment variables for every run. Set here only; agents can't set them.
session_registry_max	200	How many sessions claude_sessions remembers.

mcp_servers

A map of server name to server settings. Names may use letters, digits, - and single _. Unknown keys are an error.

Key	Default	Meaning
command, args		Start a stdio server. Set exactly one of command or url.
env	{}	Extra environment variables for the server.
inherit_env	false	Pass the runner's own environment through as well.
cwd		Working directory for a stdio server.
url, headers		Connect to a streamable-HTTP server.
allow_tools	all	fnmatch patterns of tools to relay.
deny_tools	[]	Patterns of tools never relayed. Wins over allow_tools.
call_timeout_s	270	Per-call limit.
startup_timeout_s	30	Handshake limit.
enabled	true	Switch the server off without removing it.

See Relay local MCP servers.

Files

Path	Contents
~/.fyai/runner-config.yaml	Configuration file.
~/.fyai/credentials	Saved token, used only when no OS secret store is available. Owner-only permissions.
~/.fyai/bin/fyai-runner	Binary installed by install, which self-update replaces.
~/.fyai/logs/runner.log	Log when running as a service or with log_file. Rotates at 5 MB, keeping 3 old files.
~/.fyai/logs/mcp-<server>.log	Output of each stdio MCP server.
~/.fyai/browser-profile/	Browser profile.
~/.fyai/runner.lock, runner.pid	Single-instance lock.

Connection outcomes

Situation	What the runner does
Network drop or platform restart	Reconnects with back-off (5 s doubling to 300 s, plus jitter).
Another runner connects to the same environment	This runner is disconnected and tries to reconnect. After 5 displacements in a row it backs off and logs that a duplicate runner is running.
Token rejected (expired, rotated more than 24 hours ago, revoked)	Stops with Registration token was rejected by the platform. Generate a token and start again with --token.
Environment deleted	Stops with Execution environment no longer exists on the platform.
Update available	Finishes running calls (up to update_drain_timeout_s), replaces itself and restarts. Calls arriving meanwhile get Runner is updating; please retry shortly.