NodeFox

Headless Execution

Overview

The nf runner executes the Apps and Automations you build in the browser on a machine you control. It runs as a background service and starts runs from the command line, on a cron schedule, when files land in a folder, or from an authenticated webhook. Every run leaves a record on the machine.

Note

Headless execution is included with the Pro and Enterprise plans. Other plans, including the 14-day trial, don't include headless runs. The runner needs a NodeFox sign-in, and each run fetches a short-lived run key online, so it does not run offline or air-gapped.

Requirements

PlatformRequirement
Linuxx64 or arm64, glibc 2.29 or newer (Ubuntu 20.04+, Debian 11+, Fedora 31+)
macOSApple Silicon
Not supportedWindows, Intel Mac, musl-based Linux
NetworkOutbound access to NodeFox (sign-in, run keys) and to your model providers

Install

Create an install code in NodeFox under Integrations → Command-line sign-ins → Install on a server, then run:

bash
curl -fsSL https://nodefox.ai/nf/install.sh | sh -s -- --code NF-XXXX-XXXX-XXXX-XXXX
nf version

The script downloads nf and its companions (nf-js, nf-v8) and signs the machine in with the same code. To install by hand, extract the release tarball and copy all three binaries into one directory on your PATH, such as ~/.local/bin.

Sign in

The one-line install has already signed you in. To sign in another way:

bash
nf login                 # opens a browser to approve this machine
nf login --no-browser    # prints the approval link only (SSH, servers)
nf login --code NF-…     # signs in with an install code
nf whoami                # account, plan and run key
nf logout

Add provider keys

Model requests go directly to the provider you configure, with your keys. Keys are stored in ~/.nodefox/keys.env (file mode 0600) and scrubbed from logs.

bash
nf keys set openai                                    # hidden prompt
printf '%s' "$KEY" | nf keys set anthropic --stdin    # no terminal
nf keys list                                          # values are masked
nf keys clear openai

Provider names are gemini, openai, anthropic, xai, mistral, or custom:<name> for a custom endpoint. If an Enterprise admin gave you a setup code, run nf keys setup to place your assigned keys.

Run the service

Schedules, watched folders and webhooks only fire while the service runs. Install it so it starts at login and restarts after a crash:

bash
nf service install       # launchd on macOS, systemd --user on Linux
nf service status
nf service logs -f

On a Linux server that should keep running after you log out, also run loginctl enable-linger $USER. Without the unit, nf service start and nf service stop control it by hand.

Deploy

Export the App or Automation from the browser as a .nfx file, then deploy it:

bash
nf deploy path/to/order-check.nfx
nf deploy order-check.nfx --as order-check-eu    # deploy under another name
nf deploy order-check.nfx --dry-run              # verify and show the plan only
nf undeploy order-check

To skip the download, pair the browser with this machine once and use Send to nf in the Deploy dialog:

bash
nf link            # prints a one-time pairing code
nf link --list
nf link --revoke all

The pairing link listens on 127.0.0.1 only.

Run

bash
nf x order-check region=west          # run any deployed artifact with inputs
nf app order-check --check            # preflight only; nothing runs
nf auto nightly-review                # batch an Automation
nf x order-check -d                   # submit, print the run id, exit
nf x order-check --timeout 15m

nf run is an alias of nf x. Use -i for an interactive form with live prompts, or --no-interactive to never prompt. Add --json to any command for machine-readable output.

Triggers

Each deployed artifact has one trigger, set with nf dispatch. Run nf dispatch <artifact> alone to show the current one.

Schedule

bash
nf dispatch order-check --schedule "0 7 * * 1-5" --tz America/Chicago

Standard five-field cron, no seconds. The time zone defaults to the machine's. A firing missed while the machine was asleep or the service was down is logged and skipped, never replayed. A firing whose previous run is still live is skipped.

Watched folder

bash
nf dispatch invoice-intake --watch ~/inbox/invoices --glob "*.pdf" --settle 5s

Each file that lands starts a run with that file as its input. --recursive includes subfolders, --bind <input> picks the file input when there is more than one, and --settle waits until a file stops changing (default 2s).

Webhook

bash
nf dispatch order-check --webhook              # path defaults to the artifact name
nf dispatch order-check --token                # print the URL and bearer token
nf dispatch order-check --token --rotate-token

The webhook server listens on 127.0.0.1:3040 at /hooks/<workspace>/<path>, without TLS. Every request needs the trigger's token as Authorization: Bearer <token>. A request that starts a run gets 202 with the run id and a status URL. To accept requests from other machines, put your own reverse proxy with TLS in front of it.

--method sets the accepted methods (POST, PUT, GET), --map fields maps body fields to inputs, and --map body:NAME puts the whole body into one input. --concurrency and --queue bound how many runs execute and wait.

Other modes

bash
nf dispatch order-check --once     # fire once when armed, then go back to none
nf dispatch order-check --fire     # fire now, ignoring the schedule
nf dispatch order-check --none     # trigger nothing

Error and input policies

Set these on a single run (nf x) or on the trigger (nf dispatch):

FlagValuesEffect
--on-errorfail, ask, retry:NStop the run, ask the operator, or retry a failed request up to N times (1–10)
--on-inputwait, failWhen nobody is prompting, hold a question for an answer, or fail the run
--on-budgetstop, continue, askWhat happens when a run reaches its budget

nf dispatch also accepts --max-duration to stop a trigger run after a set time.

Answering questions

A headless run that reaches a question waits in the runner. Answer it from the terminal with nf runs attach <run>, from an MCP client connected through nf mcp serve, or from a browser paired with nf link on the same machine. There is no web or mobile approval inbox for headless runs, and a pending question ends if the runner crashes.

Inspect runs

bash
nf runs                   # active runs and the last finished ones
nf runs -a                # every run
nf runs show <run>        # header, outputs, files and rows
nf runs logs <run> -f     # follow the log lines
nf runs log <run>         # the run record, one explained line per entry
nf runs attach <run>      # follow a run and answer its questions
nf runs stop <run> --reason "wrong input file"

<run> is a run id, a unique prefix, or last. Each run's record lives in ~/.nodefox/runs/<run>/: the log, transcript, diagnostics and result. Choose what is kept with nf record (for example nf record --transcript on).

Run states

StateMeaning
queuedAccepted, waiting for a slot
runningExecuting
waiting_inputStopped at a question until someone answers
completedFinished
failedEnded on an error
stoppedEnded early, for example by nf runs stop
interruptedCut off by a crash or shutdown

Interrupted runs are flagged and never re-run automatically. For single-row runs, --checkpoint N saves the engine state every N steps, and nf runs resume <run> starts a new run from the last checkpoint when you choose to.

Use it from an agent

nf mcp serve runs a stdio MCP server that lets an agent deploy, run, inspect and answer runs. Add --read-only to offer only tools that change nothing.

bash
claude mcp add nf -- nf mcp serve

Limits

  • Windows, Intel Mac and musl-based Linux are not supported.
  • MCP servers used inside a workflow, and OAuth-connected services, are not available headless.
  • Code steps are JavaScript only, in V8 isolates. On macOS the runner adds an OS sandbox; on Linux there is no OS sandbox.
  • The webhook server has no TLS of its own and binds to loopback by default.
  • Missed schedule firings are skipped, not replayed.
  • Questions are answered on or through the runner machine; there is no remote approval inbox.