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, authenticated gh, and a Git repository connected to a Netlify project.

Install nax

npm install -g @davidwells/netlify-agent-executor

Verify the command:

nax --help
nax list

Confirm the required CLIs are authenticated before initialization:

netlify status
gh auth status

Initialize the project

nax init

To preview setup before writing files or secrets:

nax init --dry

To use only local Netlify API orchestration:

nax init --no-github-actions

Preview a workflow

nax run review --dry --force

The dry run loads the flow, resolves prompts, and prints the 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 and dashboard event streaming:

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

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
Run Workflows