Skip to main content

Getting Started

This guide gets you from an empty workspace to an agent-assisted n8n workflow loop.

Prerequisites​

  • VS Code, Cursor, Windsurf, or another editor that can install VS Code extensions for the recommended flow.
  • A folder or .code-workspace.
  • An existing n8n Cloud/self-hosted URL and API key, or a local managed instance created with n8n-manager.
  • Node.js 20 or newer for CLI usage.

The Model​

GroupCommandUse it for
Primary Usagen8nac envWorkspace environments
Workspace Inspectionn8nac workspaceV4 workspace snapshot
Managed Local Instancesn8n-managerLocal managed instances and tunnels

An environment stores the workspace-safe context: n8n endpoint, project, workflowsPath, and active selection. API keys stay local.

Recommended: VS Code / Cursor​

  1. Install n8n-as-code from the Microsoft Marketplace or Open VSX.
  2. Open a folder or .code-workspace.
  3. Open the n8n view.
  4. Run n8n: Configure.
  5. In n8n environments, choose Enter URL and API key for a remote n8n environment or select a local managed instance.
  6. Choose the project and workflows path.
  7. Save the environment.

After that, use the sidebar to pull workflows or create a local workflow file, then ask the Agent Workbench for the change you want.

CLI Setup​

Install first. update-ai then writes agent instructions that name the installed binary directly; without an install they fall back to npx, which pays npm's own startup on every one of the tens of calls an agent makes per task.

Remote n8n environment​

npm install -g n8nac
n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev
n8nac update-ai

Local managed instance​

npm install -g n8nac
n8n-manager instance list
n8nac env add Local --managed-instance <id> --workflows-path workflows/local
n8nac env use Local
n8nac update-ai

If you do not have a local managed instance yet:

n8n-manager instance create
n8n-manager instance start <id>

First Sync​

n8nac list
n8nac pull <workflow-id>
n8nac push workflows/dev/my-workflow.workflow.ts --verify

Sync is explicit. The CLI and extension do not silently overwrite local or remote work.

Check Readiness​

n8nac env status --json
n8nac workspace status --json

env status --json is the source of truth for the active environment, including the resolved workflowsPath.

What Gets Created​

your-project/
├── n8nac-config.json
├── AGENTS.md
├── workflows/
│   └── dev/
│       └── my-workflow.workflow.ts
└── .git/
  • n8nac-config.json stores workspace environments and is safe to commit when it contains no secrets.
  • API keys stay local through n8nac env auth or the extension.
  • Local managed instances and tunnel state stay in n8n-manager storage.
  • AGENTS.md gives local coding agents grounded n8n instructions.

Agent Skills And Plugins​

Claude Code​

/plugin marketplace add https://github.com/EtienneLescot/n8n-as-code
/plugin install n8n-as-code@n8nac-marketplace

Generic Agent Skills​

https://github.com/EtienneLescot/n8n-as-code/tree/main/skills

Use skills/n8n-architect if an explicit path is required.

OpenClaw​

openclaw plugins install @n8n-as-code/n8nac
openclaw n8nac:setup
openclaw gateway restart

Next Steps​