Installation, configuration and every error you may run into — with step-by-step fixes. The guide covers Linux and macOS; where commands differ, it is stated explicitly.
OPENFREEDOM installs from the terminal with a single command. Zero sudo: everything lives in your home. The script checks the machine BEFORE touching anything (Python 3.10+, disk space, network) and, if interrupted, re-running the same command resumes where it left off.
curl -sSL https://openfreedom.it/installer/install.php | bash
When finished, the script starts the web UI and opens the browser. To restart OPENFREEDOM later:
~/.openfreedom/avvia-of.sh
curl -sSL https://openfreedom.it/installer/install-mac.php | bash
Same flow: installs in ~/.openfreedom, starts the web UI and opens the browser. The terminal method does not go through Gatekeeper (no quarantine).
Security note: you can read the script before running it — curl -sSL https://openfreedom.it/installer/install.php | less. If something goes wrong, the script generates diagnosi.txt with guidance.
On first launch the Provider field is empty on purpose. You choose the provider, then press 💾 Save.
.txt file from your desktop.🔴 "Invalid or expired key (401)" in the model menu
The saved key is rejected by the provider. Fix: 1) open the provider's site and check the key is active (regenerate if needed); 2) in Setup, press 🗑 Remove key; 3) paste the new key in the field (it will be hidden immediately); 4) press 🔐 Insert then 🔍 Refresh in the model menu.
🔴 "Mode without LLM not supported in Phase 1 v2… Restart with API key"
Chat cannot see a valid key. Fix: 1) open Setup (⚙️); 2) select the provider and Save; 3) insert the API key in the field (never in chat); 4) wait 2 seconds and type in chat again. No restart needed: availability updates automatically.
🟡 The "Models" menu is empty
Usually the key is missing or the provider is not saved. Fix: insert the key, press Save on the provider, then 🔍 Refresh. If the menu says "— insert the key to see models —", the key is missing; if it says "— invalid or expired key —", see the case above.
🟡 Models do not appear automatically after inserting the key
First select the provider in the menu (the field starts empty for new users), then press 🔍 Refresh. Models load from the selected provider, not from the previously saved one.
🔴 "Clone from main" without saving anything
This is correct behaviour: until you save provider+model in Setup there is no "main model". Fix: go to the LLM tab, select provider and model, press 💾 Save, then try the clone again.
🔴 401 error even with a freshly generated key (e.g. Kimi/Moonshot)
Check that the saved key is really the pasted one (in the past the masking could save asterisks: if the problem persists, Remove key and re-insert it). Then check that the chosen provider matches the key: a Moonshot key does not work on DeepSeek or OpenAI.
🔴 "Vault locked: password required for this machine"
Enter the activation password in the dedicated field (🔐 Security tab) and press 🔓 Unlock. It is the password chosen during installation.
🔴 Forgotten password
The password is derived from you and your machine: without it the encrypted data (API keys, tokens, sites) is not recoverable, by design. Fix: reinstall OPENFREEDOM and recreate the credentials (API keys must be re-entered from the provider's site). Memory and skills remain recoverable if you have a backup (see Backup section).
🟡 "No vault" or keys disappearing
The vault is not initialised or has been moved. Fix: complete the installation (run the installer once) or check that the data folder has not been deleted. Keys must be re-entered afterwards.
🟡 The voice does not speak / the toggle is off
The default speech engine uses a cloud service (Microsoft Edge TTS): internet is required. If you are offline, OPENFREEDOM uses the local fallback espeak-ng (on Linux install it with sudo apt install espeak-ng; on macOS brew install espeak-ng). Also check that the system volume is not muted.
🟡 The voice reads hashtags, links or folder paths
Up-to-date version: symbols (#, links, paths) are removed from speech automatically. If you hear them, update OPENFREEDOM to the latest version.
🟡 "Ollama unreachable"
Ollama is not running. Fix: start Ollama (Linux: ollama serve or the app; macOS: open Ollama from Applications) and retry. Also check that port 11434 is not blocked (see Network).
🔴 "No GPU detected: the Ollama section is disabled"
OPENFREEDOM disables Ollama when no GPU is found, because local models need one to be usable. Fix: check your GPU drivers (Linux: nvidia-smi or /dev/dri/renderD*; macOS: Metal is always present on Apple Silicon). If you have a GPU but it is not detected, update the drivers.
🟡 Local model install is slow or fails
Models weigh GBs and downloading takes time. If it fails with "not found in the catalogue", check the OFFICIAL name on ollama.com/library (e.g. llama3.2:3b, qwen2.5:7b). OPENFREEDOM checks your machine's requirements before downloading.
🟡 "Timeout" or "API list unreachable"
The computer cannot reach the provider (api.deepseek.com, api.moonshot.ai, api.z.ai, api.openai.com). Fix: check your connection; if you use a firewall (e.g. UFW on Linux), allow outbound HTTPS (443) to the provider. On Linux: sudo ufw status and, if needed, sudo ufw allow out 443/tcp.
🟡 The family chat (Tailscale) does not connect
The P2P chat uses Tailscale. Fix: install Tailscale, run tailscale up and press Detect in Setup. Both devices must be on the same private Tailscale network.
🔴 "curl: command not found"
curl is missing. Fix: install it from your package manager — Debian/Ubuntu: sudo apt install curl; Fedora: sudo dnf install curl; Arch: sudo pacman -S curl. (macOS already ships curl.)
🔴 Pre-flight stops: Python 3.10+ not found
OPENFREEDOM requires Python 3.10 or newer. Fix: install Python (sudo apt install python3 on Debian/Ubuntu, sudo dnf install python3 on Fedora), check with python3 --version and re-run the same install command.
🟡 The web UI does not open / port in use
The default port (8080) may be busy. Fix: close the program using it (ss -tlnp | grep 8080) or start on another port following the terminal instructions.
🟡 On Wayland screenshots or audio do not work
Wayland has stricter permissions. For screenshots use Portal support (installed by default on modern distros); for audio check the mixer. If problems persist, an X11 session is the most compatible fallback.
🟡 Gatekeeper blocks the saved script
The recommended method is curl … | bash (no quarantine). If instead you save the script and run it, always use bash install-mac.sh from Terminal: this avoids Gatekeeper blocks.
🟡 Installation is interrupted (Ctrl+C or error)
Re-run the same command: the script resumes where it left off, it does not start over. If the error persists, open ~/.openfreedom-installer/diagnosi.txt and follow its guidance — or write to team@openfreedom.it including that file.
🟡 The web UI does not open after installation
Start it manually: ~/.openfreedom/avvia-of.sh and open http://127.0.0.1:8080 in the browser. If port 8080 is busy, close the program using it or follow the terminal instructions.
🟡 RAM or GPU not detected by the hardware test
Browsers do not expose all data (precise RAM only on Chrome/Edge). It is a browser limit, not a software one. On macOS local models work well with Apple Silicon.
🟡 "You have reached the 200-task limit of the trial version"
The free trial allows 200 tasks, then it locks. Fix: buy the lifetime licence (€49.90 VAT included, launch promotion) on the site — PayPal button or QR — and receive your activation key by email. For any issue write to team@openfreedom.it.
🟡 The lock appears even after reinstalling
This is intended: the trial counter is registered server-side, tied to your machine (reinstalling does not reset it). The only way is the full licence.
OPENFREEDOM creates automatic backups of data (memory, configuration, skills). For a manual backup, copy the data folder somewhere safe. On Linux it is ~/.openfreedom/; on macOS the corresponding user folder. The backup does NOT contain secrets in clear text: without the activation password they cannot be read (by design).
For any issue not covered by this guide, write to team@openfreedom.it: we will reply right away. Include your system (Linux or macOS, version) and the exact error message.
← Back to home