The deployed UI ships with the same install/deploy guide in Spanish under
frontend/docs.html (linked as Docs in the header) — the pages below
are the English source of truth.
A permanent, searchable history for your n8n executions.
n8n prunes old executions (the default retention keeps only recent runs). This project keeps a growing copy: a small read-only Python service imports your n8n executions into its own SQLite database and serves a fast web viewer — filters, full-text search, an n8n-style execution diagram, and per-node input/output inspection.
- Read-only against n8n. No credentials, no n8n settings touched, no
writes to n8n's database (plain
SELECTs against the SQLite file). - No dependencies. Python 3 stdlib only (no
pip install), and the viewer is plain HTML/JS with no build step. - Incremental. The first run backfills everything n8n still has; every
later sync (automatic, every 5 minutes by default) imports only the delta.
A small re-scan window picks up late
running → finishedtransitions and soft-deletes. - Loopback by default. The API binds to
127.0.0.1:8391; expose it through your existing web server (Apache/nginx notes included).
Requires an n8n instance using the default SQLite database. n8n on Postgres is not supported (see Limitations).
n8n (Docker) n8n-execution-viewer
┌─────────────────────────┐ ┌──────────────────────────────┐
│ database.sqlite (WAL) │ SELECT │ sync engine (every 5 min) │
│ execution_entity │ ────────► │ decode + import (delta) │
│ execution_data │ read-only│ ▼ │
│ workflow_entity │ │ history.db (SQLite, yours) │
└─────────────────────────┘ │ ▼ │
│ API on 127.0.0.1:8391 │
Apache / nginx ◄──────────────│ ▼ │
(Alias + ProxyPass) │ static frontend │
└──────────────────────────────┘
The history database is a separate file that only this service writes, so n8n's pruning never touches it: executions you imported last month are still here after n8n has forgotten them.
On the machine where n8n runs:
curl -fsSL https://raw.githubusercontent.com/plorentec/n8n-execution-viewer/main/install.sh | sudo bash -s --The installer will:
- Find n8n's SQLite database (official Docker volume path, then
docker inspectof a running n8n container, then it asks). Pass--n8n-db PATHto skip detection. - Copy the frontend to
/var/www/n8n-viewer/and the backend to/opt/n8n-execution-viewer/. - Create and start the
n8n-viewer.servicesystemd unit (loopback API, first run backfills the history, then it syncs every 5 minutes). - Print the exact two lines to add to your Apache vhost (or patch it
itself, with a timestamped backup, a managed block and a configtest,
if you pass
--apache-conf /path/to/vhost.conf— optional--vhost-port).
Re-running it updates the code and never touches the history database.
Remove it later with sudo bash install.sh --uninstall (the history
stays on disk on purpose). Other options: --dry-run, --port,
--bind, --sync-interval, --no-systemd, --help.
Prefer to do it by hand? The manual install below is exactly what the script does, step by step.
If your company already runs n8n in Docker (compose, Portainer, plain
docker run), you have three ways to install the viewer. All three read
the database the same way — pick by how you manage your containers.
How the viewer reaches the database (all options). SQLite is not a
server: there is no port, no protocol and no credentials. It is a file.
Docker lets two containers mount the same volume, so the viewer mounts
n8n's data volume read-only (:ro) and opens
database.sqlite with SQLite's own read-only mode. n8n does not
participate and is never contacted: no token, no webhook, no API. The
:ro flag is enforced by the kernel, not by convention, so even a
buggy viewer cannot write to n8n's database. The viewer keeps its own
separate history database in its own volume — that is the only thing
it ever writes.
Prerequisites for every option:
- n8n uses SQLite (the official image's default; check for
database.sqlitein its data volume). Postgres setups are not supported. - The viewer runs on the same host/kernel as n8n. Sharing a SQLite file over NFS or a network mount is not supported (SQLite is known to corrupt over network filesystems).
- Build the image once on that host (no registry image yet):
docker build -t n8n-execution-viewer . - Find the volume name and mount point first — every option needs it:
docker inspect <n8n-container> --format \
'{{range .Mounts}}{{.Name}} -> {{.Destination}}{{println}}{{end}}'
# the official image mounts volume n8n_data at /home/node/.n8n,
# so the database file is /home/node/.n8n/database.sqliteBest when n8n is managed by a docker-compose.yml: the viewer becomes
one more service in the same file, lifecycle-managed together with n8n
(docker compose up -d brings both up after a host reboot).
services:
n8n-viewer:
image: n8n-execution-viewer
restart: unless-stopped
environment:
- N8N_DB_PATH=/data/database.sqlite # path inside the volume
volumes:
- n8n_data:/data:ro # the SAME volume n8n uses
- n8n-viewer_history:/var/lib/n8n-viewer
ports:
- "127.0.0.1:8391:8391" # loopback; front it with your proxy
volumes:
n8n-viewer_history:
# do NOT redeclare n8n_data here if your n8n service already defines
# it in this file — reuse its nameThen docker compose up -d n8n-viewer.
Best when you manage n8n from Portainer's UI or with docker run
commands and prefer not to touch your n8n stack at all. Create a new
container that attaches n8n's existing volume as external:
docker volume create n8n-viewer_history
docker run -d --name n8n-viewer --restart unless-stopped \
-e N8N_DB_PATH=/data/database.sqlite \
-p 127.0.0.1:8391:8391 \
-v n8n_data:/data:ro \
-v n8n-viewer_history:/var/lib/n8n-viewer \
n8n-execution-viewerIn Portainer: Volumes shows your n8n volume's name; Containers →
Add container → set the image, the env var, the port mapping, and add
two volumes under "Advanced settings": the n8n volume (read-only
toggle on) and a new one for the history. Updating later is
docker rm -f n8n-viewer + the same command — the history volume
survives.
Best when policy says one process per container, or you prefer a
systemd service. install.sh detects the running n8n container,
reads its volume path under /var/lib/docker/volumes/..., and installs
the Python backend (stdlib only, no packages) as a system service
reading that file read-only:
curl -fsSL https://raw.githubusercontent.com/plorentec/n8n-execution-viewer/main/install.sh | sudo bash -s -- \
--n8n-db /var/lib/docker/volumes/n8n_data/_data/database.sqlite(auto-detection covers the official volume path and a running container;
--dry-run shows every step first.) The frontend is copied to
/var/www/n8n-viewer/ and wired into Apache if present.
The viewer serves only its API on loopback. Point any web server (or Portainer's own proxy) at it — for Apache under a subpath:
Alias /n8n-viewer /var/www/n8n-viewer
ProxyPass /n8n-viewer/api/ http://127.0.0.1:8391/api/
ProxyPassReverse /n8n-viewer/api/ http://127.0.0.1:8391/api/
ProxyPass /n8n-viewer !The frontend/ files are plain static assets — any nginx, Caddy or
Traefik static route works the same way.
n8n's volume is owned by uid 1000 with 0600 files, so a non-root
user could not open the database. The image contains exactly three
small Python files and nothing else, and the n8n mount is read-only.
Copy frontend/ to a directory your web server can serve, e.g.
/var/www/n8n-viewer/. Optionally set N8N_URL at the top of app.js to
your n8n web UI base URL (e.g. https://n8n.example.com) to enable the
"open in n8n" links; leave it empty to hide them.
Copy backend/ to /opt/n8n-viewer/ (or anywhere; the paths below assume
that).
Copy deploy/n8n-viewer.service to /etc/systemd/system/ and adjust the
paths if needed:
Environment=N8N_DB_PATH=/var/lib/docker/volumes/n8n_n8n_n8n_data/_data/database.sqlite
Environment=N8N_VIEWER_DB=/var/lib/n8n-viewer/history.dbN8N_DB_PATH is where n8n's SQLite file lives. For the official n8n Docker
image with default volumes it is
/var/lib/docker/volumes/n8n_n8n_n8n_data/_data/database.sqlite; find
yours with docker inspect <n8n-container> | grep -A3 Mounts if your
volume name differs.
Then:
systemctl daemon-reload
systemctl enable --now n8n-viewer
journalctl -u n8n-viewer -f # watch the first (backfill) syncPoint the static files and the API at the viewer, e.g. Apache (the same
works with nginx; see deploy/apache-notes.conf):
ProxyPass /n8n-viewer/api/ http://127.0.0.1:8391/api/
ProxyPassReverse /n8n-viewer/api/ http://127.0.0.1:8391/api/
ProxyPass /n8n-viewer !
Alias /n8n-viewer /var/www/n8n-viewerTrap (measured): the
ProxyPasstarget must keep the/api/path — Apache maps the remainder of the URL onto the target, so a barehttp://127.0.0.1:8391/target rewrites/n8n-viewer/api/statsto/statsand the backend answers 404.
Open https://your-host/n8n-viewer/.
| Variable | Default | Meaning |
|---|---|---|
N8N_DB_PATH |
n8n Docker default volume path | n8n's SQLite file (read-only) |
N8N_VIEWER_DB |
/var/lib/n8n-viewer/history.db |
this service's history database |
N8N_VIEWER_BIND |
127.0.0.1 |
API bind address |
N8N_VIEWER_PORT |
8391 |
API port |
N8N_VIEWER_SYNC_INTERVAL |
300 |
seconds between automatic syncs |
N8N_VIEWER_PAGE_SIZE |
50 |
executions per page |
N8N_VIEWER_ADMIN_PASSWORD |
— | create the first admin at startup on a fresh install (username: admin, override with N8N_VIEWER_ADMIN_USERNAME). Without it, the UI offers a one-time first-run wizard instead |
N8N_VIEWER_OIDC_ISSUER |
— | enable Keycloak/OIDC sign-in, e.g. https://keycloak.example.com/realms/myrealm |
N8N_VIEWER_OIDC_CLIENT_ID |
— | confidential client id |
N8N_VIEWER_OIDC_CLIENT_SECRET |
— | confidential client secret |
N8N_VIEWER_OIDC_ADMIN_GROUP |
— | users whose IdP groups claim contains this get the admin role |
N8N_VIEWER_PUBLIC_BASE_URL |
— | the viewer's own base URL, used to build the OIDC redirect (<base>/api/auth/oidc/callback) |
N8N_VIEWER_RETENTION_DAYS |
0 |
keep the history this many days; 0 = keep forever. After each sync, older rows are dropped from the history (never from n8n's own database). Also --retention-days N in install.sh |
N8N_VIEWER_MAX_BLOB_MB |
50 |
skip the payload of any execution whose stored data is larger than this. The execution still appears in the list, marked as having no data, instead of being loaded and re-serialized in memory |
Two ways, in order of precedence:
- Settings panel (recommended): gear icon → Marca → title,
subtitle and logo upload. Saved via the API to
config.jsonnext to the history database (survives restarts and image rebuilds). - Static file: drop a
brand.jsonnext toindex.html(in your web root). Used only when the settings panel has not saved a brand:
{ "title": "Mi Empresa", "subtitle": "historial de n8n", "logo": "logo.png", "favicon": "favicon.png" }titlereplaces the heading,subtitlethe small caption below it, and the browser tab becomes"title · subtitle".logoreplaces the default icon (any image file, shown at 42 px).faviconreplaces the tab icon.- No file, or any field missing → the current default. Nothing else needs to change; it is plain static files, served by the same web server.
GET /api/stats returns a storage block: current size of the history
(dbBytes, percentOfDisk), free space on that disk, and an honest
estimate of the growth (estBytesPerDay, from the average imported payload
per day) with a 30-day projection (projectedBytes30d). The UI shows the
current percentage in the fifth card, details in the tooltip, and the active
retention in the card label.
GET /api/stats— totals, byStatus, deleted, importIssues, date rangeGET /api/workflows— id/name/active/deleted + total + error countsGET /api/executions?workflow=&status=&q=&from=&to=&before=— filtered list;qis an exact execution id (digits) or full-text search over node data; cursor pagination vianextBeforeGET /api/executions/:id— detail with nodes/positions/connections (diagram data) and the error boxGET /api/executions/:id/nodes/:name?run=N— node input (derived from the source run, orinputOverride), output, parameters, errorGET /api/sync— running/step/last run result (retentionDeletedrows dropped by the retention window,retentionSkippedexecutions too old to import again,oversizedBlobspayloads skipped byN8N_VIEWER_MAX_BLOB_MB)POST /api/sync(headerx-viewer-action: sync) — trigger a sync now;409while one is runningGET /api/config— currentretentionDays+brand(title/subtitle/logo)POST /api/config(headerx-viewer-action: config, JSON body{retentionDays?, brand?}) — update them; persists toconfig.jsonnext to the history DB;400on invalid values,403without the header
The settings panel (gear icon in the header) edits both through that endpoint: the retention period (how long executions are kept in the history) and the brand (title, subtitle, logo upload). The workflow sidebar is sorted by execution count (most executed first).
Dates are passed through verbatim as n8n stores them
(YYYY-MM-DD HH:mm:ss.mmm); the viewer renders them in your local
timezone.
n8n does not store the execution payload as a plain JSON object. The
execution_data.data column holds a flatted array (measured on
n8n 2.29.10, decoded against the parser n8n ships itself in
@n8n/backend-common):
- It is a JSON list of unique values (dicts, lists and strings);
entry
0is the root. - Every string appearing inside the structure is the string form of the index of the real value in the list (a shared object, or a primitive).
- Numbers, booleans and null stay inline.
backend/sync.py→flatted_resolveis a faithful Python port of that parser (shared references and cycles included).
Other 2.x specifics handled by the importer (all measured on 2.29.10):
execution_entityhas nolastNodeExecuted/executionDataId; the last node is read from the decoded payload.- The workflow snapshot is a separate column (
workflowData), merged into the stored blob, so the diagram still works for rows whose run data n8n has pruned. startDatasits at the top level of the payload (legacy nested form is also accepted).- A run's input provenance is
run["source"]— a list of source objects (previousNode/previousNodeOutput/previousNodeRun); legacy runs (inputSource/sourcestring) are still understood. workflow_entitymarks removed workflows withisArchived(legacydeletedAtis probed too).
If you upgrade n8n to a version that changes this schema, the sync fails
loudly with n8n schema not recognized: … and the already-imported history
keeps being served. File an issue — the fix is usually a few lines in
backend/sync.py.
The whole test suite runs on a synthetic n8n database that serializes the real 2.x flatted format, so it exercises the production shape, not a simplification:
cd backend
python3 -m unittest discover -s tests -v- SQLite only. n8n configured with Postgres/MySQL is not supported; the sync engine reads the SQLite file directly (that is what makes it dependency-free and safe).
- Binary data is shown as references (
fileName,mimeType) — the viewer never copies the binary blobs. - UI language is Spanish for now; the API is language-neutral.
- The history database grows (~a few hundred MB per day on a busy instance); it is a plain SQLite file you can delete/rotate at will.
Everything behind /api/* requires a session; the static files (login
screen included) stay public. Two roles:
- admin — settings, retention, branding, user management, manual sync
- viewer — browse the history only
Local accounts live in the viewer's own database; passwords are stored with PBKDF2-SHA256 (600k iterations). Sessions are signed HttpOnly cookies that survive restarts. Login is rate-limited per user+IP (5 failures in 15 minutes → lockout) and never reveals whether the account exists. Admins can require a TOTP second factor (Settings → Mi 2FA; QR or manual secret into any authenticator app).
First run: open the UI — a one-time "Configurar por primera vez"
wizard creates the first admin (only offered while no users exist), or
set N8N_VIEWER_ADMIN_PASSWORD before starting.
Keycloak / any OIDC provider: create a confidential client with a
valid redirect URI <public-base-url>/api/auth/oidc/callback, set the
five N8N_VIEWER_OIDC_* variables and restart. "Entrar con Keycloak"
appears on the login screen; roles come from the group claim. The token
exchange is server-to-server and identity is read from the userinfo
endpoint, so the backend stays dependency-free. Local accounts keep
working as a fallback when the IdP is down.
- The backend opens n8n's database read-only (
file:...?mode=ro) and never writes to it; with n8n's WAL mode, read-only connections do not block the running instance. - The API is loopback-only by default. If you expose it, keep it behind a
reverse proxy that restricts access (the notes in
deploy/show the minimal Apache changes on a LAN/Tailscale-only host). - No credentials are needed or stored anywhere for reading n8n: the database file is opened read-only at the filesystem level. The viewer's own users are separate (see the section above).