From 916316be6dc250c1fd630ed391609b73fddfde72 Mon Sep 17 00:00:00 2001 From: Ian Clarke Date: Mon, 27 Jul 2026 21:36:16 -0500 Subject: [PATCH 1/2] docs: document data locations and resource limits Users ask where Freenet keeps its data and how to cap what the peer uses, and the answer wasn't on the site. The only place a data path appeared was the uninstall guide, in the context of deleting it. Adds /configuration/ with the per-OS data, config, and log paths, how to edit config.toml and restart, and the resource settings that matter (hosting storage budget, module cache, blocking threads, connection counts, bandwidth limits) with their defaults and an example config for a light-touch peer. Linked from the FAQ and quickstart troubleshooting. Values verified against freenet-core main (crates/core/src/config.rs, ring/hosting/cache.rs, tracing/tracer.rs) as of 0.2.112. [AI-assisted - Claude] Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Nt3ybmxRb7F3vVfpANnZQ5 --- hugo-site/content/about/faq/index.md | 7 ++ hugo-site/content/configuration/_index.md | 97 +++++++++++++++++++++++ hugo-site/content/quickstart/_index.md | 3 + 3 files changed, 107 insertions(+) create mode 100644 hugo-site/content/configuration/_index.md diff --git a/hugo-site/content/about/faq/index.md b/hugo-site/content/about/faq/index.md index 5ee86195..728fa716 100644 --- a/hugo-site/content/about/faq/index.md +++ b/hugo-site/content/about/faq/index.md @@ -23,6 +23,7 @@ aliases: - [Can I follow Freenet on social media?](#can-i-follow-freenet-on-social-media) - [How can I financially support Freenet development?](#how-can-i-financially-support-freenet-development) - [How do I uninstall Freenet?](#how-do-i-uninstall-freenet) +- [Where does Freenet store data, and how do I limit what it uses?](#where-does-freenet-store-data) - [Why does the Freenet project use and mention AI tools?](#why-does-the-freenet-project-use-and-mention-ai-tools) Freenet is a fully decentralized, peer-to-peer network and a drop-in replacement for the world wide @@ -289,6 +290,12 @@ On Windows, `freenet uninstall` has a known gap and may leave the config folder The [Uninstall guide](/uninstall/) has the full per-platform manual-fallback snippets (Linux systemd, macOS launchd, Windows PowerShell) for when the binary is missing or broken. +# Where does Freenet store data, and how do I limit what it uses? {#where-does-freenet-store-data} + +On macOS everything lives in `~/Library/Application Support/The-Freenet-Project-Inc.Freenet`, with logs in `~/Library/Logs/freenet`. On Linux it's `~/.local/share/freenet` for data and `~/.config/freenet` for configuration. On Windows it's under `%LOCALAPPDATA%\The Freenet Project Inc\Freenet`. + +How much disk, memory, and bandwidth the peer uses is set in `config.toml` in the configuration directory. Edit it and restart the peer. The [data locations and resource limits](/configuration/) page lists the settings, their defaults, and an example configuration for a peer that should stay out of your way. + # Why does the Freenet project use and mention AI tools? {#why-does-the-freenet-project-use-and-mention-ai-tools} Freenet does not require AI, depend on AI, or embed AI into the platform. Users and contributors can diff --git a/hugo-site/content/configuration/_index.md b/hugo-site/content/configuration/_index.md new file mode 100644 index 00000000..b26bcfea --- /dev/null +++ b/hugo-site/content/configuration/_index.md @@ -0,0 +1,97 @@ +--- +title: "Data Locations & Resource Limits" +date: 2026-07-27 +draft: false +--- + +Freenet runs a peer in the background. The peer stores contracts, talks to other peers, and uses +some disk, memory, and bandwidth on your machine. This page shows where that data lives and how to +cap what the peer uses. + +## Where Freenet stores data + +| | macOS | Linux | Windows | +|---|---|---|---| +| Data (contracts, delegates, secrets, database) | `~/Library/Application Support/The-Freenet-Project-Inc.Freenet` | `~/.local/share/freenet` | `%LOCALAPPDATA%\The Freenet Project Inc\Freenet\data` | +| Configuration (`config.toml`) | same directory as data | `~/.config/freenet` | `%LOCALAPPDATA%\The Freenet Project Inc\Freenet\config` | +| Logs | `~/Library/Logs/freenet` | `~/.local/state/freenet` | `%LOCALAPPDATA%\freenet\logs` | + +Inside the data directory you'll find `contracts/` (contract code and state), `delegates/`, +`secrets/` (your keys), `db/`, and `wasmtime-cache/` (compiled contract code). + +To see how much space it's using on macOS: + +```bash +du -sh ~/Library/Application\ Support/The-Freenet-Project-Inc.Freenet +``` + +Logs look after themselves: files older than 72 hours are deleted at startup, and the log directory +is capped at 512 MB. + +## Changing settings + +Freenet writes a `config.toml` in the configuration directory above, and reads it on every start. +Edit that file, then restart the peer. + +Two rules to avoid a peer that won't start: + +- **Edit the generated file, don't write your own.** Freenet needs the whole file, including the + paths and key locations it wrote itself. A partial `config.toml` fails to parse and the peer + refuses to start. +- **If it does refuse to start, delete `config.toml` and restart.** Freenet regenerates it with + defaults. Your data and keys are untouched. + +Restart the peer after editing: + +- **macOS (Freenet.app):** click the rabbit in the menu bar and choose **Restart**. +- **Linux, or a macOS install via `install.sh`:** `freenet service restart` +- **Windows:** restart Freenet from the tray icon. + +Every setting below also works as a command-line flag (`--max-hosting-storage`) or an environment +variable (`MAX_HOSTING_STORAGE`) if you run `freenet network` yourself, but the background service +started by the installer reads only `config.toml`. + +## Resource limits + +These are the settings worth knowing about. The names on the left are the `config.toml` keys. + +| Setting | Limits | Default | +|---|---|---| +| `max-hosting-storage` | Bytes of contract state the peer keeps for the network. Once past it, contracts are evicted least-useful-first and their disk reclaimed. | 1/8 of system RAM, at least 128 MB and at most 1 GB | +| `hosting-disk-pct` | Fraction of the data disk's capacity used as a second ceiling on the same eviction. | `0.5` | +| `max-hosting-disk` | Hard cap for that disk ceiling. | 32 GB | +| `module-cache-budget-bytes` | Memory for cached compiled contract code. Delegates get a further 1/4 of this. | 1/8 of system RAM, at least 64 MB and at most 4 GB | +| `max_blocking_threads` | Threads used to run contract code, which is the peer's main CPU cost. | 2x CPU cores, at least 4 and at most 32 | +| `max-number-of-connections` | Peer connections accepted. | `200` | +| `min-number-of-connections` | Peer connections the node tries to maintain. Lowering this is the single biggest lever on idle bandwidth. | `25` | +| `total_bandwidth_limit` | Bytes per second across all connections. Unset means no aggregate cap. | unset | +| `bandwidth_limit` | Bytes per second for a single large transfer. | `3000000` (3 MB/s) | + +Note the mixed dashes and underscores. Copy the key names exactly as written above. + +The disk that contract hosting actually uses is the smaller of the RAM-derived budget +(`max-hosting-storage`) and the disk-derived one (`hosting-disk-pct` of the disk, capped by +`max-hosting-disk`). On a typical laptop the RAM-derived budget binds first, so +`max-hosting-storage` is the setting to change. + +### Example: a light-touch peer on a laptop + +Add or edit these lines in the generated `config.toml`: + +```toml +max-hosting-storage = 268435456 # 256 MB of contract state +module-cache-budget-bytes = 134217728 # 128 MB of compiled-code cache +min-number-of-connections = 10 +max-number-of-connections = 40 +total_bandwidth_limit = 1000000 # 1 MB/s total +max_blocking_threads = 4 +``` + +All values are in bytes. A peer configured this way still works, it just hosts less for other +people and contributes less to the network. + +## Related + +- [Uninstalling Freenet](/uninstall/) if you want it gone entirely. +- [Matrix chat](https://matrix.to/#/#freenet-locutus:matrix.org) if something here doesn't match + what you see. diff --git a/hugo-site/content/quickstart/_index.md b/hugo-site/content/quickstart/_index.md index a7d83446..df539217 100644 --- a/hugo-site/content/quickstart/_index.md +++ b/hugo-site/content/quickstart/_index.md @@ -53,6 +53,9 @@ system-wide service instead: `sudo freenet service install --system` **Network requirements:** Freenet uses UDP hole punching for peer-to-peer connections. Most home routers support this without configuration. Strict corporate firewalls may block connections. +**Using too much disk or bandwidth?** See [data locations and resource limits](/configuration/) for +where Freenet stores things and how to cap what the peer uses. + Need to remove Freenet? See the [uninstall guide](/uninstall/). ## What's Next? From 9e274a099f831ed527628e4b6d9a53453bdabe05 Mon Sep 17 00:00:00 2001 From: Ian Clarke Date: Mon, 27 Jul 2026 21:36:55 -0500 Subject: [PATCH 2/2] docs: correct the flag/env-var note (not every setting has an env var) [AI-assisted - Claude] Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Nt3ybmxRb7F3vVfpANnZQ5 --- hugo-site/content/configuration/_index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/hugo-site/content/configuration/_index.md b/hugo-site/content/configuration/_index.md index b26bcfea..12310296 100644 --- a/hugo-site/content/configuration/_index.md +++ b/hugo-site/content/configuration/_index.md @@ -47,9 +47,10 @@ Restart the peer after editing: - **Linux, or a macOS install via `install.sh`:** `freenet service restart` - **Windows:** restart Freenet from the tray icon. -Every setting below also works as a command-line flag (`--max-hosting-storage`) or an environment -variable (`MAX_HOSTING_STORAGE`) if you run `freenet network` yourself, but the background service -started by the installer reads only `config.toml`. +The settings below also work as command-line flags (`--max-hosting-storage`) if you run +`freenet network` yourself, and most have an environment variable too. Run `freenet network --help` +for the exact flag and variable names. The background service started by the installer takes no +flags, so `config.toml` is the only way to configure it. ## Resource limits