Getting your data into the engine

The engine is a small Python program, borewatch, that watches folders, builds the dashboard objects, detects events, encrypts and pushes. Everything it writes stays in a folder you choose.

011. Install (one click)

The download page detects your operating system: Windows gets BoreWatch-Setup.exe (double-click, no admin rights), macOS and Linux a one-line terminal installer. Both create the drop folder, register a background service that runs the engine at sign-in, and open the first-time setup, which asks for the tenant id and push secret from the welcome mail and for your data passphrase.

# manual alternative (Python 3.10+)
pip install borewatch
borewatch init --tenant t_xxxx --server https://app.borewatch.com
borewatch install                 # folders + background service (optional)

The config is written to ~/.borewatch/config.json (readable by your user only). borewatch doctor checks Python, folders, the licence and connectivity; borewatch folders prints every path.

022. Drop files in one folder (automatic sorting)

Dump anything into the drop folder - C:\Users\<you>\BoreWatch\Raw_Data on Windows, ~/BoreWatch/Raw_Data on macOS / Linux - in any structure, zips included. On every run the engine sniffs each file's content, moves it to Sorted/<WELL>/mudlog|geology|loss|survey/ and builds from there. Files it cannot classify go to Sorted/_unsorted (rename with the well name and drop again). Already-sorted files are never duplicated.

032b. Register extra data sources (optional)

borewatch add "D:\RigData\Mudlogs"                    # recursive; CSV, LAS, WITSML XML
borewatch add "D:\RigData\Geology" --kind geology       # interval tables (CSV / XLSX)
borewatch add "D:\RigData\Surveys" --kind survey        # MD / INC / AZI or MD / TVD tables
borewatch sources                                       # list, with the wells detected in each

Well naming. The well name is taken from the file name (for example WELL-12_MLT_2026-02-17.csv gives WELL-12), from a Hole ID column, or from the WITSML nameWell. Override per folder with --well, or give a regular expression with --well-regex. A field name for the dashboard's field dropdown comes from the prefix before the first dash (DA) or from --field "Demo Field A".

043. Supported formats

Mudlog / EDR time series (required)

Format	Detection	Notes
CSV with a header row	Column names + optional units in [ ] or ( )	Any sampling rate; rows are median-aggregated to 1 minute. Nulls: empty, -999.25, NaN.
RTTI / Pason / NOV exports with mnemonic headers	Mnemonic row + description rows	Long names in the metadata row are matched to channels.
LAS 2.0 (time or depth indexed)	~C curve section mnemonics	Depth-indexed LAS populates the depth view only.
WITSML 1.4.1.1 log XML	logCurveInfo mnemonics	One file per log or a folder of partial logs.

Channels are matched by a built-in alias table (ROP, WOB, RPM, TQA/torque, SPP, flow in, SPM, pit volumes, paddle, MW in/out, ECD, mud temperatures, MWD temperature, hook load, hole depth, bit depth, TVD, block position). Run borewatch map FILE to see what was matched and write a mapping.json for anything that was not:

{ "Rate of Penetration (m/hr)": "rop", "Weight on Bit (klbs)": "wob", "Torque (kN.m)": "tq_avg:knm" }

Units are converted when known (ft, m; klb, t, kN; psi, bar; gpm, l/min; ppg, sg; degC, degF; kft.lb, kN.m). The dashboard always shows the canonical unit.

Geology intervals (optional)

CSV or XLSX with From, To and any of: Rock name, Rock type, Lava, Tuff, Intrusion (percent), Alt type, Alt intense value (0-5), MeB, mineral columns (smectite, illite, chlorite, epidote, silica, calcite, pyrite, oxide, zeolite, quartz, hematite; 0-5 or percent), Lithology description, Remarks. The header row is found automatically.

Loss zones (optional)

From, To, Type (PLC / TLC), Rate (bph), Volume (bbl), Remarks.

Surveys, elevation and casing (optional)

Survey CSV with MD, INC, AZI (minimum curvature is applied) or MD, TVD. Elevation and casing in a small JSON or CSV per well: rkb_masl, gl_masl; casing rows od_in, type, top_md, shoe_md, hole_in. Templates: borewatch template elevation, borewatch template casing.

054. Build, detect, push

borewatch build                 # incremental: only wells whose files changed
borewatch detect                # rule-based events -> out/events.json
borewatch push                  # uploads changed *.enc.json (ciphertext) to your tenant
borewatch run                   # build + detect [+ analogs, trajectories, AI] + push, once
borewatch run --watch           # the same every time a source file changes (and at least hourly)
borewatch status                # licence, last push, wells, sizes

Schedule borewatch run with Task Scheduler or cron if you prefer not to leave a process running. The engine is idempotent and never re-uploads unchanged objects.

064b. Updates and reinstalls

The dashboard shows a notice when a new version is published (on PC, Mac and phones, also when installed as an app from the browser menu); reloading keeps layouts and settings. The engine checks once a day and prints a notice; borewatch update upgrades in place, or re-run the installer. Program files, data (Raw_Data, Sorted), config and built objects / caches live in separate folders: install, update and borewatch uninstall never erase your data or work in progress (--purge-data is the only way).

075. Local mode (no upload)

Open the dashboard, sign in, choose Open local folder and pick the engine's out/ folder. The browser reads the files directly; nothing is uploaded. Requires Chrome or Edge on a desktop.

086. Add-on modules

• Analogs and Map & 3D are computed by the engine when the licence includes them (borewatch run picks this up automatically).
• AI Monitor & Ask: set ANTHROPIC_API_KEY on the workstation (or borewatch set ai.api_key ...). The engine writes a short written analysis per well whenever new events appear; the dashboard's Ask box uses the same key from your browser.
• Alerts: borewatch set alerts.telegram_token ... alerts.telegram_chat ... or an SMTP block for email; high-severity events are sent as they are detected.

097. Users and seats

The owner account can add and remove users from the dashboard's Account page up to the seat limit; new users get their own password by email. Share the data passphrase with them through your own channel - we never have it.

108. Troubleshooting

Symptom	Cause and fix
"no readable mudlog rows"	Timestamp column not recognised. Run borewatch map FILE and map it to time (or date + clock).
Depth view empty	Needs hole depth and bit depth (or a depth-indexed LAS). Map depth and bitpos.
"wrong passphrase" in the browser	The engine key and the browser key differ. Check borewatch status (shows the key fingerprint) against the dashboard's Account page.
Push refused (402)	Licence ended or more active wells than licensed. borewatch status shows which.