n8n Workflow Manager

Deutsche Version · English

Local-first workflow review, visual inspection, decision-tracked editing, history, and multi-server sync for n8n.

• System Architecture
• Workflow Lifecycle
• Governance & Runtime Invariants
• Visual Interface & Screenshots
• Target Audience Personas & SEO
• Architecture & Feature Comparison
• What it does
• Install and start
• CLI examples
• Builder API
• Configuration and data
• Docker
• Remote n8n setup
• Manager + MCP pairing
• Sibling Ecosystem
• Verification
• License

graph TD
    Client["Client Interfaces<br/>(Browser Web UI / CLI / REST API / MCP)"]
    FastAPI["FastAPI Application<br/>(127.0.0.1:8100)"]
    Engine["n8nManager Engine<br/>(Decision Audit & Version Control)"]
    SQLite[("SQLite History DB<br/>(%LOCALAPPDATA%/n8n-workflow-manager)")]
    Remote["Remote n8n Instances<br/>(n8n Public REST API)"]

    Client -->|"HTTP / CLI Commands"| FastAPI
    FastAPI --> Engine
    Engine -->|"Store Mutation & History"| SQLite
    Engine -->|"Sync Pull / Push"| Remote

The following sequence demonstrates how operations (such as building or mutating a workflow) require an explicit audit decision, persist immutable snapshots into SQLite, sync to remote n8n servers, and enable deterministic rollback.

sequenceDiagram
    autonumber
    actor User as "Operator / AI Agent (MCP)"
    participant API as "FastAPI Gateway (127.0.0.1:8100)"
    participant Engine as "n8nManager Engine"
    participant SQLite as "SQLite History DB"
    participant n8n as "Remote n8n API"

    Note over User,n8n: "1. Decision-Tracked Mutation & Push Flow"
    User->>API: "POST /api/workflows/build (Name, Nodes, Decision)"
    API->>Engine: "Validate Workflow Graph & Payload"
    Engine->>SQLite: "Record Revision Snapshot & Mutation Decision"
    SQLite-->>Engine: "Saved as Version N"
    Engine->>n8n: "Sync Push Workflow (Public REST API)"
    n8n-->>Engine: "HTTP 200 OK (Remote Workflow ID)"
    Engine-->>API: "Operation Receipt & Updated Version"
    API-->>User: "JSON Status (ID, Version, Audit Hash)"

    Note over User,n8n: "2. Safe Rollback Flow"
    User->>API: "POST /api/workflows/{id}/rollback (Target Version, Decision)"
    API->>Engine: "Retrieve Target Version Snapshot"
    Engine->>SQLite: "Query History Snapshot (Version K)"
    SQLite-->>Engine: "Historical Workflow JSON Payload"
    Engine->>SQLite: "Record Rollback Event & Audit Trail"
    Engine->>n8n: "Push Restored State to Remote Server"
    n8n-->>Engine: "HTTP 200 OK (Reverted Active State)"
    Engine-->>API: "Rollback Confirmed"
    API-->>User: "Restored Version Receipt"

The browser UI provides interactive workflow inspection, node dependency graphing, and history management without leaving your local environment:

Dashboard & Workflow Overview	Visual Graph Viewer & Live Inspector
Workflow catalog, server bindings, revision counts & quick actions	Interactive vis.js graph, node parameters, credentials & connections

n8n Workflow Manager is purpose-built for technical teams, operators, and AI agents requiring strict governance over automation workflows:

• [PERSONA-01] Workflow Automation Engineers & Sysadmins: Operators managing complex multi-stage n8n instances across staging, testing, and production who require cross-server syncing, visual graph diffing, and zero data egress.
• [PERSONA-02] AI Agent Framework Architects & MCP Integrators: Teams integrating LLMs (via n8n-manager-mcp) to autonomously construct or modify workflows, governed by mandatory human-in-the-loop decision rationales (--decision).
• [PERSONA-03] Security & Compliance Officers: Security teams requiring immutable SQLite audit trails, redaction of sensitive credentials, offline vendored frontend assets, and strict adherence to non-elevation (RunAsInvoker).
• [PERSONA-04] DevOps & Site Reliability Engineers (SRE): Infrastructure teams deploying pinned container images (docker-compose.yml), automated backups, cursor-paginated REST APIs, and instant deterministic rollback.

• local n8n workflow manager, visual n8n graph viewer, n8n multi-server sync, decision-tracked workflow automation, n8n-manager-mcp companion, local-first workflow rollback, vis.js n8n editor, fastapi n8n controller, offline n8n documentation export.

Comparison of n8n-workflow-manager with standard deployment and management alternatives across core operational dimensions:

• Visual graph viewer and working browser editor for n8n workflow JSON.
• SQLite-backed version history and decision audit for every mutation.
• Rollback through the REST API or CLI.
• Per-workflow/per-server pull/push bindings using the n8n public API and cursor pagination.
• JSON and Markdown export, validated imports, and bundled generic templates.
• FastAPI REST API, Swagger UI, and a terminal CLI.

The application is local-first: it binds to 127.0.0.1 by default and stores configuration and runtime data in per-user directories rather than inside the installed package or source checkout.

pip install git+https://github.com/ellmos-ai/n8n-workflow-manager.git
n8n-manager serve

Open http://127.0.0.1:8100. Interactive API documentation is at http://127.0.0.1:8100/docs.

For development:

git clone https://github.com/ellmos-ai/n8n-workflow-manager.git
cd n8n-workflow-manager
python -m pip install -e ".[dev]"
python -m pytest -q

Mutations that can replace or remove state require a short decision. It is stored with workflow history.

n8n-manager import workflow.json --decision "Import reviewed customer workflow"
n8n-manager list
n8n-manager history 1
n8n-manager export 1 --format md

n8n-manager servers --add production https://n8n.example.com YOUR_API_KEY --default
n8n-manager push 1 --decision "Deploy reviewed version"
n8n-manager pull
n8n-manager rollback 1 2 --decision "Restore last known-good version"

n8n-manager status                       # effective paths, database and server state
n8n-manager config --show                # inspect the resolved configuration
n8n-manager config --set db_path ./my.db # change a single setting

TLS verification is on by default. --no-verify-tls exists for controlled local environments with self-signed certificates; do not use it across untrusted networks.

curl -X POST http://127.0.0.1:8100/api/workflows/build \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webhook forwarder",
    "decision": "Create a reviewed draft",
    "nodes": [
      {"type": "n8n-nodes-base.webhook", "name": "Trigger", "parameters": {"path": "hook"}},
      {"type": "n8n-nodes-base.httpRequest", "name": "Forward", "parameters": {"url": "https://api.example.com"}}
    ],
    "connections": [{"from_node": "Trigger", "to_node": "Forward"}]
  }'

See API_REFERENCE.md for the mutation and history contracts.

n8n-manager status prints the effective paths. Relative db_path values are resolved below the user data directory.

Overrides: N8N_MANAGER_CONFIG, N8N_MANAGER_CONFIG_DIR, and N8N_MANAGER_DATA_DIR. Start with config.example.json. The default trusted_hosts accepts only loopback Host headers; explicitly list the reviewed public hostname when using an authenticated reverse proxy.

docker compose up --build -d

The Compose port is bound to 127.0.0.1:8100, and state is mounted below runtime/. The image runs as an unprivileged user.

The setup command expects Docker to have been installed according to the remote host's operating-system policy. It installs a pinned official n8n image on a loopback-only port; it does not run a remote curl | sh installer.

n8n-manager setup --host your-server --user deploy --ssh-key ~/.ssh/id_ed25519
# Follow the printed ssh -L ... tunnel command, then open http://127.0.0.1:5678

SSH uses batch mode and StrictHostKeyChecking=accept-new. For public service, provide an authenticated TLS reverse proxy. Do not expose either n8nManager or the generated n8n listener directly to the internet.

n8n-workflow-manager and n8n-manager-mcp are designed as a pair: the MCP server is the AI action layer, while this project is the human state-and-history layer with visual review, per-workflow decisions, versions, and rollback. A client can read /api/workflows/{id}/history before submitting the required decision for a mutation.

The authoritative decision log lives here and is client-independent, so the same review trail can cover the MCP server, curl, the CLI, or the web UI.

If you are running n8n as part of a self-hosted stack rather than standalone, ellmos-stack brings up n8n together with Ollama and a document index via Docker Compose; this manager then connects to that instance like to any other n8n server. Conversational context can additionally come from a pull-based history index such as ctx (Apache-2.0).

n8n-workflow-manager is an integral component of the ellmos-ai and open-bricks open-source ecosystems:

The release contract is documented in RELEASE_GATE.md. The core local gates are:

python -m pytest -q
python -m ruff check n8nManager tests
python -m bandit -q -r n8nManager -lll
python -m pip_audit
python -m build

MIT; see LICENSE. Use at your own risk; no warranty or maintenance commitment is provided.

That license covers the code written for this project. The repository and the built distributions also ship the browser library vis-network (dual licensed Apache-2.0 or MIT; used here under the MIT option), which keeps its own copyright holders. Full notices: THIRD_PARTY_LICENSES.md.