Skip to content

Add HARPER_SAFE_MODE documentation #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ethan-Arrowood merged 1 commit into from
Apr 29, 2026
+20 −0
Merged

Add HARPER_SAFE_MODE documentation #486

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions reference/configuration/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,3 +207,23 @@ logging:
- Invalid values are caught by Harper's configuration validator at startup
- Changes to these variables require a Harper restart to take effect
- The state file is per-instance (stored in the root path)

---

## HARPER_SAFE_MODE

Setting `HARPER_SAFE_MODE` to any value starts Harper without loading user applications or components. Harper's core services (database, operations API, HTTP server) start normally, but no applications from the components directory are loaded and no package-based extensions are initialized.

```bash
HARPER_SAFE_MODE=1 harperdb
```

This is useful when a broken or misbehaving component prevents Harper from starting. Safe mode lets you access the operations API to inspect, repair, or remove the problematic component without needing to manually edit files on disk.

Safe mode skips:

- Installing registered applications
- Loading components from the components directory
- Loading package-based extensions defined in component configs

Built-in plugins (REST, HTTP, operations API, etc.) and the core database are unaffected.