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.
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
| Platform | Requirement |
|---|---|
| Linux | x64 or arm64, glibc 2.29 or newer (Ubuntu 20.04+, Debian 11+, Fedora 31+) |
| macOS | Apple Silicon |
| Not supported | Windows, Intel Mac, musl-based Linux |
| Network | Outbound 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:
curl -fsSL https://nodefox.ai/nf/install.sh | sh -s -- --code NF-XXXX-XXXX-XXXX-XXXX
nf versionThe 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:
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 logoutAdd 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.
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 openaiProvider 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:
nf service install # launchd on macOS, systemd --user on Linux
nf service status
nf service logs -fOn 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:
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-checkTo skip the download, pair the browser with this machine once and use Send to nf in the Deploy dialog:
nf link # prints a one-time pairing code
nf link --list
nf link --revoke allThe pairing link listens on 127.0.0.1 only.
Run
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 15mnf 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
nf dispatch order-check --schedule "0 7 * * 1-5" --tz America/ChicagoStandard 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
nf dispatch invoice-intake --watch ~/inbox/invoices --glob "*.pdf" --settle 5sEach 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
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-tokenThe 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
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 nothingError and input policies
Set these on a single run (nf x) or on the trigger (nf dispatch):
| Flag | Values | Effect |
|---|---|---|
--on-error | fail, ask, retry:N | Stop the run, ask the operator, or retry a failed request up to N times (1–10) |
--on-input | wait, fail | When nobody is prompting, hold a question for an answer, or fail the run |
--on-budget | stop, continue, ask | What 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
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
| State | Meaning |
|---|---|
queued | Accepted, waiting for a slot |
running | Executing |
waiting_input | Stopped at a question until someone answers |
completed | Finished |
failed | Ended on an error |
stopped | Ended early, for example by nf runs stop |
interrupted | Cut 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.
claude mcp add nf -- nf mcp serveLimits
- 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.