From files to your first well.

Install the engine, connect your data and review the well. This guide covers formats, setup and troubleshooting.

Install (one click)

BoreWatch runs on Windows 10 / 11. Download BoreWatch-Setup.exe with the link in your welcome email (lost it? get a new link) and double-click it (no admin rights). The setup window asks for two things, plus your acceptance of the Terms of Service, and nothing has to be typed into a command prompt:

• License key - one serial from your welcome email, BW-XXXXX-XXXXX-.... Paste it; the window checks it as you type.
• dataPass - chosen by you, at least 8 characters. It encrypts your data on your computer before anything is uploaded, and you type it in the dashboard to open (decrypt) your data. We never receive it and cannot recover it, so the setup also saves a recovery kit to print.

Before Install becomes available, tick I have read and accept the BoreWatch Terms of Service (Read the terms opens the full text; borewatch terms prints it later). Acceptance is required and is asked again when the terms change.

Setup then creates the drop folder, registers a background service that runs the engine at sign-in, opens the drop folder for you and shows buttons to print the recovery kit and open the dashboard. Nothing opens a command window: setup, the background service and runs asked for from the dashboard are silent (their log is %USERPROFILE%\.borewatch\engine.log). Current engine version: 1.8.6.

A new license key (Account → New license key in the dashboard): run the setup again, tick Use a new license key and paste it. Your dataPass and data stay as they are.

Update data from the dashboard. The engine sorts the drop folder every few seconds and rebuilds when a file changes, at least every hour. To force it, press Update data in the dashboard header (also in the Account sheet and the more-menu): the engine, which checks in every 30 seconds, sorts the drop folder, rebuilds and uploads at once, and the dashboard tells you when the new data landed and offers a reload. When nothing in the drop folder changed, the engine (1.7.2 or newer) reports that back and the dashboard says so at once; an engine older than 1.7.1 never sees the request, and the dashboard tells you to update it.

Forgot your password? Use Forgot password? on the sign-in page: a link to choose a new password is mailed to the account address and works for 1 hour. Signed in, you change it under Account → Change my password.

Forgot your dataPass, or want a new one? BoreWatch never has it, so it cannot be mailed. Open your data with the code from your printed recovery kit, or run the setup again on the engine computer and tick Choose a new dataPass: every well is re-encrypted and uploaded again, you use the new dataPass in the dashboard from then on, and the setup writes a new recovery kit (the old one stops working).

The config is written to %USERPROFILE%\.borewatch\config.json (readable by your user only). borewatch doctor checks Python, folders, the license and connectivity; borewatch folders prints every path. Typed in a terminal, a command prints there (the prompt comes back right away, as for any windowless program); borewatch init and borewatch set-key, which ask you something, open a window of their own.

Drop files in one folder (automatic sorting)

Dump anything into the drop folder - C:\Users\<you>\BoreWatch\Raw_Data - 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.

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_mudlog_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".

Supported formats

Mudlog / EDR time series (required)

Channels are matched by a built-in alias table (ROP, WOB, RPM, TQA/torque, SPP, flow in, SPM, pit volumes, flow out, 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.

Well header and casing tables (optional, recommended)

Drop them with the data; no config editing needed. Well header: one row per well with Well, Field, Pad (optional), Easting, Northing, RKB, GL (any metric grid; elevations in meters unless the header says [ft]): puts the wells on the map and names the fields. Casing: one row per string with Well, Type, OD [in], Top MD, Shoe MD. Values already in the config win. The sample data (linked in your welcome email) has an example of each.

Feed zones (engine 1.7.6 or newer): one row per feed zone from a completion or injectivity test with Well, Feed zone MD (a point depth, meters unless the header says [ft]) and Rank (major / intermediate / minor) and/or Contribution [%]; optional Test, Test date, Basis. Each feed zone is drawn as a disc on the map and 3D view, sized by its share or rank, and on the image-log sticks.

Daily reports (engine 1.7.7 or newer): geology and loss tables usually lag the drilling by days. Drop the rig's daily geology or loss table too, with daily report (or provisional) in the file name and the same columns as the main table. Its geology is used only below the deepest depth of the geology table (newest report first), and its losses only where the loss table has no entry; the dashboard draws them dashed and adds (daily report) to the readout, until the main tables catch up.

Data residency audit

In short: your well data stays on your computer. Only encrypted objects, which we cannot open, reach our server; no value, word, path or secret from your files leaves in readable form. This audit is how we check it.

We run the real engine on the public sample data (21 wells, 527 files) against a recording server, and capture every byte it sends: every DNS lookup, every connection and every request body. Anything addressed to a host other than this computer is logged and blocked. Then we search the captured traffic for what must never leave the computer. Last run: 2026-11-13, engine 1.8.3. Summary: residency-audit.json.

Every network call the engine can make

With the built-in model, Ollama or the rule-based narrator, the AI analysis and Ask stay on your computer. If you choose the Anthropic API or an OpenAI-compatible endpoint, the AI prompt (a compact summary of the well and your question) goes to that provider under your own account and terms.

More on how the encryption works: Security.

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                # license, last push, wells, sizes
borewatch export                # model hand-off folder now (also written by every run that changed a well)

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.

Model hand-off. After every build that changed a well, the engine writes a Model_Handoff folder next to your drop folder (borewatch folders shows where) with the files your other packages import: Leapfrog well-data tables (collar, survey as depth / azimuth / dip, interval tables for lithology with alteration, MeB and minerals, loss zones, casing and drilling parameters per meter, point tables for markers, events and feed zones); one LAS 2.0 file per well for Techlog, WellCAD, Interactive Petrophysics or Strater (TVD, TVDSS, every drilling and mud-log channel, and the geology as logs: lithology and alteration codes, intensity, MeB, minerals, loss zones; datum, coordinates and CRS in the header); for Petrel, well heads (name, UWI, X, Y, KB, TD in MD and TVD), well paths (MD X Y Z TVD DX DY AZIM INCL DLS), well tops (markers, lithology and alteration boundaries, casing shoes and liner tops, loss zones, feed zones, TD), drilling events as point well data, casing and the code tables of the discrete logs, with the LAS files as its logs; PetraSim well data files (completed interval as elevations, well path); completion-test feed zones and loss-zone candidates; and GeoJSON (longitude / latitude when your CRS is a UTM zone) plus a CSV with WKT for QGIS or ArcGIS. The folder's README has the import steps. Set "handoff": false in the config to switch it off. These are plain files on your own disk. Since engine 1.7.4 the folder is also published encrypted with the other dashboard data, so the dashboard's ⋯ → Export for other software can build a zip of the formats and wells you tick, on any computer or phone, decrypted in your browser; our servers only hold ciphertext.

Updates and reinstalls

The dashboard shows a notice when a new version is published (on computers 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).

Local mode (no upload)

Open the dashboard, sign in, type your dataPass and choose Open local folder instead. Pick the engine's out folder, C:\Users\<you>\.borewatch\out (picking your user folder works too). The browser reads the files directly; nothing is uploaded. The dashboard remembers the folder, so the next time it opens straight away after the browser's permission prompt. Requires Chrome or Edge on a desktop.

Add-on modules

• Analogs and Map & 3D are computed by the engine when the license includes them (borewatch run picks this up automatically). The 3D view switches between a perspective and an orthographic (true-scale, no vanishing point) camera with Pers / Ortho beside Fit and Up; the choice is kept with the view and in session files.
• AI analysis and Ask (included in every plan): the engine on your workstation writes a short analysis per well whenever new events appear (the analysis: AI Monitor notes and offset-well summaries) and answers questions from the dashboard's Ask box. Choose the model for each in the dashboard under ⋯ → AI settings:
  • Built-in model (default): Qwen3-4B (Apache 2.0) through llama.cpp, downloaded once (2.5 GB) when you tick it in the setup window or press Download and use in AI settings, checked against a pinned SHA-256, and run on the engine computer only (it listens on 127.0.0.1, starts when needed and stops after 20 idle minutes). No API key; nothing leaves the computer. Needs 8 GB of memory. borewatch ai shows its state, borewatch ai download fetches it from a terminal.
  • Anthropic API with your own key, any OpenAI-compatible endpoint (a company LLM gateway, Azure OpenAI proxy, LM Studio, vLLM) or Ollama. Keys typed in AI settings are encrypted in your browser with your dataPass key and stored on the engine computer only; only the account owner can change the settings.
  • Automatic uses what you set up yourself first, then the built-in model, then (for the analysis) the rule-based narrator. Analysis and Ask can use different models and effort levels; test checks each one.
  From a terminal: borewatch reasoning --for analysis|ask|both --backend auto|builtin|api|openai|ollama|rules [--model M] [--effort low|medium|high|max]. Questions and answers travel encrypted; your data never goes to BoreWatch.
• Alerts: borewatch set alerts.telegram_token ... alerts.telegram_chat ... or an SMTP block for email; high-severity events are sent as they are detected.

Saving images. More menu (⋯) → Save image (PNG) saves what the open tab shows at 1 to 4× resolution: tracks, compare, the map, the 3D scene or the image-log (XRMI) chart. Buttons, menus, input boxes and on-screen panels are left out, so the picture holds the content only. In the XRMI tab, Wells… chooses which wells are drawn; hidden wells are also left out of the saved image.

Users and seats

Sample data: the link is in your welcome email, or ask for it again (tick include the sample data). It holds 21 synthetic wells: one field each for geothermal, oil & gas and mineral drilling, two wellpads per field and 3 to 4 wells per pad, with every file type the engine reads, including a well header table (field, wellpad, coordinates, rig elevation), a casing table and, for the geothermal wells, a feed-zone table and one well's daily geology and loss report. Drop the ZIP into Raw_Data as it is.

BoreWatch is licensed per user. One subscription is one person: one sign-in, one encrypted data space and one engine license key. The dashboard works on 1 registered computer and 1 registered phone or tablet per user: the first computer and the first phone that sign in are registered, and any other device is refused, even with the right password. To change device, remove the old one under Account → Devices, or choose Use this device instead when signing in on the new one (a 6-digit code is emailed; at most 3 moves in 30 days). The engine runs on 1 PC and does not use a device slot; to move it, release the old PC under Account → Devices (a PC that has not uploaded for 14 days is released automatically). Extra devices are an add-on. Colleagues subscribe separately and get their own data spaces; several engine PCs, a shared team data space and single sign-on (SSO) are Enterprise options.

Your dataPass is chosen by you and known only to you, and to anyone you decide to share it with. We never have it and cannot recover it.

Students. University and college students apply on the student page with an academic email address (for example .ac.id, .edu, .ac.uk): access with every add-on starts at once for 1 month, and is extended to 3 months from the start once the student's objectives, thesis or paper have been reviewed.

Troubleshooting