Configuration reference

nax keeps configuration intentionally small: most behavior is declared in workflow files or selected through command flags. This page collects the remaining surfaces that affect flow discovery, transport selection, prompt delivery, dashboard development, and artifact handling.

Project workflow discovery

nax.config.json


{
  "flowsDirs": [
    ".github/nax-flows",
    "tools/nax/flows"
  ]
}

You can also use:


nax list --flows-dir tools/nax/flows
NAX_FLOWS_DIRS=tools/nax/flows,.github/nax-flows nax list

Project config files may use YAML, JSON, TOML, or a JavaScript/TypeScript file containing a single JSON5-compatible static object export. Dynamic module code is blocked during flow discovery.

Prompt delivery

Variable	Default	Purpose
`NAX_SAFE_PROMPT_BYTES`	`16384`	Maximum final decorated UTF-8 bytes submitted by the SDK.
`NAX_PROMPT_BLOB_DISABLE`	unset	Set to `1` or `true` to limit SDK delivery to inline/compact and disable compatibility-path blob offload.
`NAX_BLOB_RETRY_ATTEMPTS`	`3`	Attempts for legacy GitHub issue/comment blob commands.
`NAX_BLOB_CLEANUP_TTL_HOURS`	`24`	Age after which legacy registry refs are eligible for cleanup.
`NAX_OUTPUT_BUDGET`	unset	Appends response-size guidance when truthy.
`NAX_OUTPUT_BUDGET_BYTES`	`64000`	Target output size when guidance is enabled.

Dashboard development

Variable	Purpose
`NAX_DASHBOARD_API_URL`	Backend origin or `/api` path used by Vite dev.
`VITE_NAX_DASHBOARD_API_URL`	Vite-facing equivalent.
`NAX_DASHBOARD_TOKEN`	Token injected into the Vite dev client.
`NAX_DASHBOARD_DEPLOYMENT_MODE`	`local`, `desktop`, or `web` capability mode.
`NAX_DASHBOARD_WEB_CAN_START_RUNS`	Allows hosted web dashboard run starts when set to `1`.
`NAX_DASHBOARD_WEB_CAN_DRY_RUN`	Allows hosted web dashboard dry runs when set to `1`.

State and debugging

Variable	Purpose
`NAX_STATE_LOCK_TIMEOUT_MS`	Timeout for workflow state lock acquisition.
`NAX_STATE_LOCK_STALE_MS`	Age after which a lock is treated as stale.
`NAX_DEBUG_ARTIFACTS`	Enables extra local artifact debugging output.
`NAX_INCLUDE_COST`	Includes estimated USD cost beside Netlify credit usage.

⚠️

Disabling blob offload is risky for synthesis-heavy workflows. If the SDK’s compact prompt still exceeds the final decorated byte budget, submission fails with prompt-too-large before the agent starts.

Configuration reference

Project workflow discovery

Prompt delivery

Dashboard development

State and debugging

See also