Skip to Content
Get Started

Get started

This tutorial takes a new checkout from install to a working nax dry run. It assumes you already have a GitHub repository and a Netlify project, because nax submits real repository work to Netlify Agent Runner rather than simulating agents locally.

Prerequisites: Node 20+, authenticated netlify-cli, and a Git repository connected to a Netlify project.

Install nax

npm install -g netlify-agent-executor

Verify the command:

nax --help
nax list

Initialize the project

nax init

To preview setup before writing files or secrets:

nax init --dry

Preview a workflow

nax run review --dry --force

The dry run loads the flow, resolves prompts, and prints the council plan without creating GitHub issues, Agent Runner jobs, or .nax artifacts.

Run for real

nax run review

Force local Netlify API orchestration when you want resume support, dashboard event streaming, and fast local follow-up:

nax run review --transport netlify-api

Inspect the result

nax handoff -c
nax dashboard review

Artifact checkpoint

Completed workflows write summaries under:

.nax/workflows/<workflow-run-id>/artifacts/summary.md
.nax/agent-runners/<runner-id>/summary.md
.nax/agent-sessions/<session-id>/summary.md

On the first non-dry run in a project, nax also adds .nax/ to .gitignore if no equivalent rule exists. The one-time check is recorded in .nax/state.json, so removing that ignore rule later is respected.

Common mistakes

⚠️

A dry run intentionally does not create .nax artifacts. Use it to verify the plan, then run the workflow without --dry when you want results.

  • Running before gh or netlify are authenticated.
  • Running against a branch whose pinned SHA has not been pushed.
  • Rebuilding the dashboard with an older Node version.

Next steps

Last updated on
For Agents