FAQ & troubleshooting
General
Section titled “General”Do I need an account?
Section titled “Do I need an account?”No. Oleafly has no accounts and no login. Install it and write. See the Philosophy.
Does it need the internet?
Section titled “Does it need the internet?”Only for a few explicit things: fetching a LaTeX package the first time a document uses it, citation lookups, cloud AI providers (local Ollama excepted), GitHub sync, and update checks. Writing, compiling (after first fetch), spellcheck, grammar, diagrams, and Preflight all run offline. Offline mode (Settings, General) guarantees the compiler never touches the network.
Where are my files?
Section titled “Where are my files?”Plain folders under ~/.openleaf/projects/, each with your .tex, .bib, images, and a real .git repo. Back them up, copy them, or open them with other tools freely. See Where your data lives.
Is the PDF output ATS-friendly?
Section titled “Is the PDF output ATS-friendly?”Yes. The Tectonic engine emits real selectable Unicode text with embedded subset fonts, and the ATS-badged resume templates follow single-column, linear-reading-order rules. Then Preflight shows you exactly what a parser extracts from your PDF, so you’re not taking anyone’s word for it.
How is this different from Overleaf?
Section titled “How is this different from Overleaf?”Short answer: everything runs on your machine, offline, for free, with your files in real Git repos. Long answer with tables: Why Oleafly.
Install
Section titled “Install”macOS says the app is damaged or can’t be checked
Section titled “macOS says the app is damaged or can’t be checked”The builds aren’t notarized yet. Right-click the app and choose Open, or clear the quarantine flag once; the exact commands are in the install guide.
Windows SmartScreen blocks it
Section titled “Windows SmartScreen blocks it”Click More info, then Run anyway. Same cause: unsigned builds, on the roadmap.
Which Linux distributions work?
Section titled “Which Linux distributions work?”Anything 2024-era or newer (glibc 2.39+): Ubuntu 24.04+, Fedora 40+, Debian 13+. AppImage, deb, and rpm are all published.
Compiling
Section titled “Compiling”My first compile is slow
Section titled “My first compile is slow”That’s the one-time package fetch: Tectonic downloads what your document needs and caches it. Every compile after that is fast and offline. See Compiling.
A package is missing and the compile errors out
Section titled “A package is missing and the compile errors out”If Offline mode is on, turn it off for one compile so the package can be fetched and cached, then turn it back on.
The compile succeeded but with warnings. Do I care?
Section titled “The compile succeeded but with warnings. Do I care?”You still got a PDF (the amber chip tells you). Click Logs to read them; undefined references and citations are the warnings most worth fixing, and Preflight pinpoints those precisely.
An error I don’t understand
Section titled “An error I don’t understand”Open Logs for the parsed error list, or just ask the AI: “fix the LaTeX errors” runs a compile-read-fix-verify loop with your approval on every change.
Word/HTML/Markdown export needs pandoc?
Section titled “Word/HTML/Markdown export needs pandoc?”Yes, and Oleafly downloads it for you automatically on first use. No manual install. See Export formats.
AI assistant
Section titled “AI assistant”Which providers work?
Section titled “Which providers work?”OpenAI, Anthropic, Z.AI (GLM), Groq, OpenRouter, DeepSeek, Mistral, xAI, and Ollama for fully local models. Models and setup: Set up AI.
The AI says it has no key / errors on send
Section titled “The AI says it has no key / errors on send”Open Settings, AI Assistant and check that a provider has a saved key and the green Active badge. The error messages themselves usually say what’s wrong: invalid key, empty balance, or rate limit.
Can I run it fully offline?
Section titled “Can I run it fully offline?”Yes: install Ollama, ollama pull llama3.2, then Check for Ollama in settings. No key, no cloud.
Can the AI change my files without asking?
Section titled “Can the AI change my files without asking?”No. Every file-changing tool pauses for your approval with a diff, and the assistant checkpoints your project in Git before its first edit. See Chat & tools.
GitHub sync
Section titled “GitHub sync”I don’t see a device code when connecting
Section titled “I don’t see a device code when connecting”Try again in a moment, or use the PAT route under “Advanced: use a personal access token” in Settings, GitHub.
Push fails with “No remote ‘origin’”
Section titled “Push fails with “No remote ‘origin’””Publish the project first (Source Control, Publish to GitHub). Push and Pull need a remote to exist.
Push says the remote has commits
Section titled “Push says the remote has commits”Pull first, then push. The ahead/behind indicator next to the branch pill warns you before this happens.
Can I sync across two computers?
Section titled “Can I sync across two computers?”Yes: push on one, pull on the other. The workflow is spelled out in GitHub sync.
A pull hit a merge conflict
Section titled “A pull hit a merge conflict”Oleafly shows the raw Git message and leaves resolution to you: fix it with any Git tool (the project is a normal repo), then keep working in the app.
Data & backups
Section titled “Data & backups”How do I back everything up?
Section titled “How do I back everything up?”Add ~/.openleaf/projects/ to your normal backup, export a .zip per project, or push to GitHub. All three, ideally. See Where your data lives.
I deleted a project. Can I get it back?
Section titled “I deleted a project. Can I get it back?”Deleting removes the folder from disk, so: from your backup or from GitHub if you pushed it. Files deleted inside a project can come back via Git history if they were ever committed.
Can I edit project files with another editor?
Section titled “Can I edit project files with another editor?”Yes, they’re plain files. Do it while the project is closed in Oleafly (or reopen it afterward), so the app’s autosave doesn’t overwrite your external changes with what it had in memory.