Appearance
Phengos — Known Issues
Current limitations and known behaviors, with workarounds where they exist. These are things to be aware of in this version; some are planned for a future update.
Ollama is text-only
Phengos sends text prompts to Ollama. Even when a local model is itself vision-capable, image and file inputs are not sent to Ollama in the current version — attaching images as context only takes effect with the cloud providers.
Workaround: use a cloud provider (Anthropic, OpenAI, or Mistral) when you need to send images as context. Local-model image input for Ollama is planned for a future release.
See Ollama.
Updating a system-wide install needs your package manager
When Phengos was installed from a .deb or .rpm package, it lives in a system-owned location and Phengos does not try to overwrite it itself. Instead, the updater downloads the new package and shows you the exact apt or dnf command to run. This is deliberate — silently elevating privileges to swap a root-owned binary is exactly the kind of thing Phengos does not do (see Security Model).
Workaround: run the command Phengos shows you (it is copied ready to paste). This is a one-line, fully visible step rather than a hidden auto-update.
See Updates & Crash Reporting.
Tarball self-update cannot update a root-owned install
The tarball (.tar.*) build can update itself in place by downloading the new version, staging it, and swapping on exit. This works when the installation directory is writable by your user. If you extracted the tarball into a system-owned location (for example under /opt or /usr/local owned by root), the in-place swap cannot replace the files and the update will not complete.
Workaround: install the tarball somewhere your user owns (such as your home directory), or re-extract the new version manually over the old one.
Tarball self-update has no post-launch auto-rollback
For tarball installs, the self-swap removes the previous version's backup as part of finishing the update. It does not wait to confirm that the newly installed version launches successfully before doing so. In the rare case that the new version is installed but then fails to start, Phengos cannot automatically roll back to the prior version.
Workaround: if a tarball update leaves Phengos unable to start, re-download and re-extract the version you want from the releases page. Keeping your own copy of the previous tarball is a safe habit until you have confirmed the new version runs.
AppImage updates depend on $APPIMAGE
The AppImage update path identifies the running image through the $APPIMAGE environment variable so it knows which file to replace. If Phengos is launched in a way that does not set $APPIMAGE (for example, certain launchers or unusual invocations), the in-place update cannot locate the image to swap.
Note: the AppImage format is not currently part of the published builds; this caveat applies only if an AppImage build is reintroduced.
Android packaging caveats
The Android build is the newest target and carries a few known rough edges:
- Generate + Patch mode is a beta feature and is currently limited to Anthropic Sonnet and Opus models on every platform, Android included. The Mode selector shows this caveat when Patch is selected. See Work Modes.
- Android receives updates as a signed
.apkthrough the standard install flow rather than an in-place swap.
API keys are not saved without a Linux keyring
Phengos stores API keys in your operating system's secret service. On Linux, if no keyring (secret service) is available — common on minimal or headless setups — there is nowhere safe to keep the key, so it is not saved. The app works, but you will have to re-enter your API key every time you start it.
Workaround: install and run a secret service such as GNOME Keyring so Phengos has a secure place to store the key between runs. macOS and Windows provide this by default.
See Key Security and Data Locations.
Notes on infrastructure (provider-side)
A couple of behaviors depend on provider-side configuration rather than on Phengos:
- Anthropic web search must be enabled for your organization. OpenAI and Mistral web search work without extra account setup, but Anthropic's web search has to be turned on for your Anthropic organization before the toggle has any effect. See Providers & Models.
- OpenAI file output needs a named file. OpenAI models reliably return an extractable file only when you explicitly name the output file in your prompt. See Providers & Models.
If you hit something not listed here, check the Error Reference for specific messages, or the FAQ for common questions.