n8n-local

n8n-local is an n8n server that can be easily integrated into your applications. It provides APIs without authentication, no initial user setup required, and automatic bidirectional synchronization of workflows and credentials with a local data folder.

⚠️ IMPORTANT: Personal Use Only

This tool is ONLY for personal use on your own machine.

Intended Use:

• ✅ Personal development and testing
• ✅ Local automation on your own computer
• ✅ Learning and experimentation

Not Intended For:

• ❌ Distribution to others
• ❌ Commercial use
• ❌ Any use beyond personal/local use on your own machine

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Data Sync
• REST API Endpoints

Features

• 🚀 No Initial User Setup - Ready to use out of the box, no user registration or setup required
• 🔓 APIs Without Authentication - All REST API endpoints work without authentication tokens (auto-login enabled by default)
• 🔁 Auto Sync - Automatic bidirectional synchronization of workflows and credentials between n8n and local data folder with file watching

Installation

npm install "@easynet/n8n-local"

Quick Start

n8n-local

The server will be available at http://127.0.0.1:9991. All APIs work without authentication - no setup required!

Configuration

Configuration is done via environment variables in the .env file. Key settings:

| Variable | Description | Default | |----------|-------------|---------| | N8N_PORT | Server port | 9991 | | N8N_AUTO_LOGIN | Enable auto-login (APIs without auth) | true | | N8N_DISABLE_USER_MANAGEMENT | Disable user management (no setup required) | true |

Auto Sync Configuration

Workflows and credentials are automatically synced to the data/ folder in the current directory. The sync is bidirectional:

• Changes in n8n → automatically saved to local files
• Changes to local files → automatically synced back to n8n
• File watching enables immediate sync when files are modified

Data Sync

n8n-local automatically synchronizes your workflows and credentials between n8n and a local data/ folder. This allows you to:

• Version control your workflows and credentials using Git
• Edit workflows directly in JSON files using your favorite editor
• Backup your workflows and credentials as files
• Share workflows by copying JSON files

The sync happens automatically in both directions:

• When you create or modify a workflow in n8n, it's saved to data/workflows/{workflowId}.json
• When you create or modify a workflow file, it's imported into n8n
• The same applies to credentials in data/credentials/{credentialId}.json

By default, the data/ folder is created in your current working directory. You can specify a custom location using the dataFolder option when initializing n8n-local.

REST API Endpoints

All REST API endpoints work without authentication - no tokens or credentials required. Auto-login is enabled by default, so all requests are automatically authenticated.

All endpoints are available at http://127.0.0.1:9991 (or your configured N8N_PORT).

API Structure

n8n-local provides two types of endpoints:

1. Standard n8n Endpoints (/rest/*) - These are n8n's native API endpoints that work out of the box:

   • GET /rest/workflows - List workflows
   • GET /rest/workflows/:id - Get workflow
   • POST /rest/workflows - Create workflow
   • PUT /rest/workflows/:id - Update workflow
   • GET /rest/executions - List executions
   • GET /rest/executions/:id - Get execution
   • And other standard n8n endpoints

2. n8n-local Custom Endpoints (/rest/n8n-local/*) - These are custom endpoints provided by n8n-local with enhanced functionality:

   • DELETE /rest/n8n-local/workflows/:id - Delete workflow (auto-archives before deletion)
   • POST /rest/n8n-local/workflows/:id/activate - Activate workflow
   • POST /rest/n8n-local/workflows/:id/deactivate - Deactivate workflow
   • POST /rest/n8n-local/workflows/:id/execute - Execute workflow (unified endpoint, auto-detects trigger type)
   • GET /rest/n8n-local/workflows/:id/executions - List workflow executions
   • DELETE /rest/n8n-local/executions/:id - Delete execution
   • POST /rest/n8n-local/chat/workflow/:workflowId - Chat Trigger workflows (legacy, redirects to unified endpoint)
   • GET /rest/n8n-local/chat/session/:sessionId - Get chat session history
   • DELETE /rest/n8n-local/chat/session/:sessionId - Clear chat session
   • GET /rest/n8n-local/chat/execution/:executionId - Get execution details
   • And other custom endpoints

Note: The /rest/n8n-local/ prefix is used to avoid conflicts with future n8n API versions and clearly identifies custom n8n-local functionality.

Workflow API Endpoints

Description: Retrieve a list of all workflows.

Query Parameters:

• active (optional): Filter by active status (true or false)
• tags (optional): Filter by tags (comma-separated list)

Request Body: None

Response:

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "active": true,
      "nodes": [...],
      "connections": {...},
      "createdAt": "ISO date string",
      "updatedAt": "ISO date string",
      "tags": [...]
    }
  ]
}

Description: Retrieve a specific workflow by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string",
    "name": "string",
    "active": true,
    "nodes": [...],
    "connections": {...},
    "createdAt": "ISO date string",
    "updatedAt": "ISO date string",
    "tags": [...]
  }
}

Description: Create a new workflow.

Query Parameters: None

Request Body:

{
  "name": "string (required)",
  "nodes": [...],
  "connections": {...},
  "active": true,
  "tags": [...]
}

Response:

{
  "data": {
    "id": "string",
    "name": "string",
    "active": true,
    "nodes": [...],
    "connections": {...},
    "createdAt": "ISO date string",
    "updatedAt": "ISO date string",
    "tags": [...]
  }
}

Description: Update an existing workflow by its ID.

Query Parameters: None

Request Body:

{
  "name": "string",
  "nodes": [...],
  "connections": {...},
  "active": true,
  "tags": [...]
}

All fields are optional

Response:

{
  "data": {
    "id": "string",
    "name": "string",
    "active": true,
    "nodes": [...],
    "connections": {...},
    "createdAt": "ISO date string",
    "updatedAt": "ISO date string",
    "tags": [...]
  }
}

Description: Delete a workflow by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string"
  }
}

Description: Activate a workflow by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string",
    "active": true
  }
}

Description: Deactivate a workflow by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string",
    "active": false
  }
}

Description: Execute a workflow by its ID. This unified endpoint automatically detects the trigger type and routes to the appropriate implementation. Supports:

• Chat Triggers (@n8n/n8n-nodes-langchain.chatTrigger) - Send messages to chat workflows
• Manual Triggers (n8n-nodes-base.start or n8n-nodes-base.manualTrigger) - Execute with optional input data
• Form Triggers (n8n-nodes-base.formTrigger) - Submit form data
• Other trigger types - Executes the workflow with its default trigger behavior

Note: The server automatically detects the trigger type - you don't need to specify it. The endpoint routes to the appropriate handler internally.

Query Parameters: None

Request Body for Chat Triggers:

{
  "messages": ["Hello", "How are you?"],
  "sessionId": "optional-session-id",
  "lastExecutionId": "optional-execution-id",
  "isNewWorkflow": false,
  "chatHistory": []
}

For chat workflows, you can also use:

{
  "message": "Hello"  // Single message (will be converted to array)
}

Request Body for Manual/Form Triggers:

{
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

Optional: Input data for the workflow execution

• For Manual Triggers: Data will be passed to the Start/Manual Trigger node
• For Form Triggers: Data should match the form fields (form submission data)
• For Other triggers: Data may be ignored depending on trigger type

Response:

{
  "status": "success",
  "data": {
    "executionId": "string",
    "finished": true,
    "data": {...}
  }
}

Response for Chat Triggers:

{
  "status": "success",
  "data": {
    "sessionId": "string",
    "response": "string",
    "executionId": "string",
    "transcript": [...],
    "messageCount": number,
    "lastExecutionId": "string",
    "executionDetails": {...}
  }
}

Execution API Endpoints

Description: Retrieve a list of all workflow executions.

Query Parameters:

• workflowId (optional): Filter by workflow ID
• status (optional): Filter by status (success, error, waiting, running)
• finished (optional): Filter by finished status (true or false)
• limit (optional): Limit results (default: 20)
• cursor (optional): Pagination cursor

Request Body: None

Response:

{
  "data": [
    {
      "id": "string",
      "finished": true,
      "mode": "string",
      "retryOf": "string | null",
      "retrySuccessId": "string | null",
      "startedAt": "ISO date string",
      "stoppedAt": "ISO date string | null",
      "workflowId": "string",
      "workflowData": {...},
      "status": "string"
    }
  ],
  "nextCursor": "string | null"
}

Description: Retrieve a specific execution by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string",
    "finished": true,
    "mode": "string",
    "retryOf": "string | null",
    "retrySuccessId": "string | null",
    "startedAt": "ISO date string",
    "stoppedAt": "ISO date string | null",
    "workflowId": "string",
    "workflowData": {...},
    "data": {...},
    "status": "string"
  }
}

Description: Delete an execution by its ID.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string"
  }
}

Description: Retrieve all executions for a specific workflow.

Query Parameters: Same as /rest/executions

Request Body: None

Response: Same format as /rest/executions

Description: Retrieve the last successful execution for a specific workflow.

Query Parameters: None

Request Body: None

Response:

{
  "data": {
    "id": "string",
    "finished": true,
    "status": "success",
    "mode": "string",
    "startedAt": "ISO date string",
    "stoppedAt": "ISO date string",
    "workflowId": "string",
    "workflowData": {...},
    "data": {...}
  }
}

Chat API Endpoints

Description: Legacy endpoint for executing Chat Trigger workflows. This endpoint is kept for backward compatibility but internally redirects to the unified POST /rest/n8n-local/workflows/:id/execute endpoint.

Note: For new integrations, use the unified endpoint POST /rest/n8n-local/workflows/:id/execute which automatically detects trigger types. This legacy endpoint will continue to work but may be deprecated in future versions.

Query Parameters: None

Request Body:

{
  "sessionId": "string (optional, auto-generated if not provided)",
  "messages": ["string"] or "message": "string (required)",
  "lastExecutionId": "string (optional)",
  "isNewWorkflow": boolean (optional),
  "chatHistory": [
    {
      "sender": "user" | "bot",
      "message": "string",
      "timestamp": "ISO date string"
    }
  ] (optional)
}

Response:

{
  "status": "success",
  "data": {
    "sessionId": "string",
    "response": "string",
    "executionId": "string",
    "transcript": [...],
    "messageCount": number,
    "lastExecutionId": "string",
    "executionDetails": {...}
  }
}

Note: For regular (non-Chat Trigger) workflows, use POST /rest/n8n-local/workflows/:id/execute instead.

Description: Retrieve the chat history for a specific session.

Query Parameters: None

Request Body: None

Response:

{
  "status": "success",
  "data": {
    "sessionId": "string",
    "transcript": [
      {
        "sender": "user" | "bot",
        "message": "string",
        "timestamp": "ISO date string"
      }
    ]
  }
}

Error Response (404):

{
  "status": "error",
  "message": "Session not found"
}

Description: Clear all messages from a chat session.

Query Parameters: None

Request Body: None

Response:

{
  "status": "success",
  "message": "Session cleared successfully"
}

Description: Retrieve detailed execution information for a chat workflow execution.

Query Parameters: None

Request Body: None

Response:

{
  "status": "success",
  "data": {
    "executionId": "string",
    "status": "success" | "error" | "waiting" | "running",
    "finished": true,
    "startedAt": "ISO date string",
    "stoppedAt": "ISO date string",
    "duration": 1234,
    "nodeExecutions": [
      {
        "nodeName": "string",
        "nodeType": "string",
        "status": "success" | "error" | "running",
        "executionTime": 123,
        "error": "string"
      }
    ],
    "error": "string"
  }
}

Error Response (404):

{
  "status": "error",
  "message": "Execution not found"
}

Important: This setup is intended for personal/local use only. Do not expose these endpoints to the internet without proper security measures.

Support

For issues and questions, please open an issue on GitHub.

Related Projects

• n8n - Workflow automation tool