--- title: Backup, retention and disk usage order: 5 description: Every file BxLens writes and where it lives, what to back up and what to leave out, how long saved data is kept, how the size cap works and how to read disk usage. icon: lucide:hard-drive --- # Backup, retention and disk usage BxLens has no database. It writes a few small files, and with BoxLang+ a store folder. This page lists all of them, says which ones matter and shows how retention and the size cap work. ## What is written, and where Paths are relative to the BoxLang home (the runtime home), unless a setting says otherwise. | File or folder | Written by | What it holds | Setting | |---|---|---|---| | `config/bxlens-settings.json` | Settings page (BoxLang+) | Your live setting changes, as `{ "overrides": { ... } }`, and the MCP servers of Lensy under `mcp`. No secrets. | `console.overridesFile` | | `config/bxlens-layout.json` | Bar designer (BoxLang+) | The order and visibility of the bar tabs. | none | | `config/bxlens-registration.json` | Register page | The registration key of this server (Free and Trial). | `registration.key`, `registration.keyEnv` | | `config/bxlens-secrets/` | Secret Store (all editions) | `secrets.key` (the key), `secrets.json` (the sealed values) and `secrets.lock`. | `secrets.dir`, `LENS_SECRETS_KEY` | | `lens-data/` | The disk store (BoxLang+) | One subfolder per server, see below. | `store.dir` | | `/bxlens-audit.log` | The audit log | Logins, denied attempts and every change, no secrets. | BoxLang logging settings | | A private folder in the temp directory | Heap dumps (BoxLang+) | One `.hprof` file, deleted 5 minutes after the download or 10 minutes after it was written. | `console.allowHeapDump` | The store folder, for one server `web-a`: ```text lens-data/ web-a/ instance.json heartbeat: who this is, last write errors.json error groups with samples reports.json report totals health.json the health snapshot, saved every minute notifications.json notification settings of the cluster (no secrets) alert-state.json what was already announced, per person and channel reports-state.json which report was sent last daily-2026-10-21.json the day's numbers for the email reports http-rollup-2026-10-21.json outgoing HTTP, buckets of ten minutes ai-rollup-2026-10-21.json AI numbers, buckets of ten minutes ai-runs-2026-10-21.jsonl one line per AI run http-calls-2026-10-21.jsonl one line per outgoing call (collect.level full) ``` Everything in it is redacted data. No request bodies, no bound query values, no text of a sent mail and no secret in plain text. See [The store](../reference/store.md). Never in the store, and lost at a restart: the request history, the query statistics, in flight data and the list of Mail messages. They are in memory only. On **Free** the store is not used. The files that remain are the registration file, the Secret Store, the audit log, and the settings and layout files when you have saved something. ## What to back up | Item | Back up? | Why | |---|---|---| | `boxlang.json` | Yes | Your configuration. You already do. | | `config/bxlens-secrets/secrets.json` | Yes | The console passwords set in the console, the SMTP password, the AI key, the channel addresses and tokens. Sealed, so a copy of it alone is useless. | | `secrets.key` | Yes, **somewhere else** | Without it `secrets.json` cannot be opened. With it beside the data, the backup holds both and the seal protects nothing. Keep it in your secret manager, or set `LENS_SECRETS_KEY` and keep that there. | | `config/bxlens-settings.json` | Yes | Your tuned thresholds and the MCP servers. Small. | | `config/bxlens-layout.json` | Optional | Small, easy to redo. | | `config/bxlens-registration.json` | Optional | The key is in the email, and the Register page mails it again. | | `lens-data//notifications.json` | Yes, if you use alerts | Your recipients, rules, channels (without their secrets) and schedule. It lives only in the store. | | The rest of `lens-data/` | Optional | History: errors, reports, rollups. Useful for the email reports and the lifetime totals, not needed to run. | | `bxlens-audit.log` | Yes, with your logs | It is your record of who changed what. | A lost key does not harm BxLens. The stored secrets stay closed: BxLens uses `boxlang.json` again for the console password, and you enter the SMTP password, the AI key and the channel addresses again. See [Restore](#restore). ## Retention Saved data is kept by day (UTC). Three rules, all `boxlang.json` only because they delete data of other servers: | Rule | Default | What it does | |---|---|---| | `store.retentionDays` | 15, at most 30 | A server removes its own day files older than this. A higher value is cut to 30. | | `store.maxMB` | 500 | The cap for the **whole** folder, all servers together. When it is passed, each server removes its own oldest days down to its fair share (the cap divided by the number of server folders). The cap wins over the retention. | | `store.staleAfterHours` | the retention | The folder of a server that has not written for this long is removed by any server, when its heartbeat is provably stale. Lower it for an autoscaled fleet. | Pruning runs every ten minutes and at the first start. - The **monthly email report** covers the calendar month before this one, from the days that are saved. With a retention of 15 days it finds about half a month, and says so ("Data found for N of M server days"). Set `store.retentionDays` to 30 if you want full monthly reports. - The **fair share** matters on a shared volume: with `maxMB` 500 and 10 servers, each keeps about 50 MB. Raise `maxMB` with the number of servers. - A folder over the cap comes back under it after every server has pruned once. - Settings, Storage shows the current values read only. A change needs a restart. ```json title="boxlang.json: keep a month, 2 GB for the fleet, drop silent servers after a day" { "modules": { "bxLens": { "settings": { "store": { "retentionDays": 30, "maxMB": 2000, "staleAfterHours": 24 } } } } } ``` ## Disk usage - **Settings, Storage** (admin) shows *Used* against *of N MB*, the records *written*, *dropped*, *failed* and *queued*, the last error, and each server in the folder with its size and last write. - The System page lists the volumes and the folders BxLens writes to, with amber and red at `volumes.warnPct` (80) and `volumes.critPct` (90). The **Disk space** alert (BoxLang+) mails you at 90 percent by default. - *Dropped* above zero means the queue (`store.queueSize`, 20000) was full and records were thrown away. *Failed* above zero means a write error: read the last error. A full disk or a read only volume is counted and never blocks a request. - How much a server writes depends on your traffic and on `collect.level`. At `light` the HTTP rollups hold totals by host and endpoint. At `full` the list of single calls is written too. Watch *Used* for a few days before you set the cap. - The audit log has no limit of its own. BxLens does not rotate or trim it. It writes through the BoxLang logging service, so check how your BoxLang logging configuration rotates the logs directory. ## Restore 1. Stop BoxLang. 2. Put back `boxlang.json`, the `config/bxlens-*` files and the secrets folder. Put the key where it was: `secrets.key` in the secrets folder, or `LENS_SECRETS_KEY` in the environment. 3. Put back `notifications.json` into `store.dir//` if you use alerts. A server reads the newest copy from any server folder, so the one in the restored folder is found. 4. Start BoxLang. Open **Settings, Storage**: the Secrets card should say *This server can open them: yes*, and the servers list should show your folder. If the key is missing, the card says *no*. The values are not damaged. Restore the key and they open. If a console password was set in the console and its hash cannot be opened, the page says the console value is unreadable and `boxlang.json` is used. To start clean, stop BoxLang and delete `store.dir//`. You lose history and, for that folder, the notification settings and the alert state.