Helios / User guide / Troubleshooting and support
Troubleshooting and support
Fix Helios launch, sign-in, missing models, permissions, browser and package problems, and prepare a useful support report.
Helios 0.114.4 · Source reference ↗
Start with three checks
- Version: check About and your install channel. An older stable package can lack features described for the current release.
- Project: confirm the conversation folder exists and is the intended repository.
- Provider: check Settings → Accounts and Providers, then verify the provider CLI directly in a terminal.
Change one thing at a time and preserve the first useful error. Restart Helios only after active work has finished or been stopped.
Helios does not start
Run helios in a terminal and read the error. The supported package relies on system GTK4/libadwaita, WebKitGTK and VTE dependencies. A source checkout also needs the documented Python and GObject bindings.
Follow the complete source dependency list. If the shell cannot find helios, check whether the package installed successfully or use the checkout’s ./scripts/helios launcher.
A second launch normally activates the running window. Updating a package while Helios is open does not replace the code in that existing process.
A provider or model is missing
Install the relevant native CLI, complete its sign-in and refresh the provider in Settings. Confirm the CLI is reachable from the environment that launches the desktop app; a terminal-only PATH change may not reach a desktop launcher.
| Provider | Useful check |
|---|---|
| Claude | claude --version and the CLI’s account/sign-in status. |
| Codex | codex --version, then codex login status. |
| Gemini | Open agy, sign in, then inspect agy models. |
| Muse | Check the installed Muse CLI and complete muse login. |
| Kimi | Check the Kimi Code CLI and complete kimi login. |
| OpenRouter | Check the configured key, account credit and selected model’s advertised capabilities. |
See provider-specific setup. Refreshing a catalogue cannot grant access to a model your account does not include.
Sign-in or billing is unexpected
Check the active route in Settings. A provider API key in Helios’s environment can take precedence over a subscription login. Muse’s META_API_KEY is one example. OpenRouter is a metered API route.
Exporting OPENAI_API_KEY does not sign Helios’s Codex App Server in. Use Codex’s native login, or the API-key sign-in flow in Settings that passes the key to the CLI.
On per-token Claude billing, Helios requires a recent Claude Code CLI advertising --max-budget-usd. Update the CLI if that budget guard is the reason a chat refuses to start.
The agent cannot edit or access the network
If the folder is exactly your home directory, choose a project subfolder: Helios forces home-rooted conversations read-only.
Inspect Execution and read the permission mapping. Codex modes can disable network access. Gemini’s headless path cannot answer interactive approval prompts. Switching every provider to a similarly named mode does not establish the same policy.
For a session waiting on input, switch to its sidebar row and respond to the current dialog. A stale question or approval can be withdrawn when the provider ends the turn.
A session is missing, queued or appears stuck
Clear project filters, check Temporary and reload. For older history, read archive recovery.
Check whether the session needs an answer, has background activity, reached a provider quota or was budget-limited. The number of saved chats is different from the number of provider attempts that can actively run. A waiting attempt may need an existing attempt to settle.
Use Stop for the current turn when appropriate. Goal Pause changes goal state; it is not universal process cancellation. Check terminal or background output before repeating an action that may already have run.
A browser preview, terminal or screenshot fails
Check the local server’s URL, port and terminal output. Verify WebKitGTK, VTE and desktop-portal dependencies for source installs. The desktop screenshot portal may ask you to select a window or area.
A composer thumbnail does not mean every provider receives native image input. See the image capability table and browser debugging checklist.
Missions or Shared is empty
These panes depend on separate optional services. Missions needs a tandem installation; Shared needs a configured scratchpad. Their absence does not prevent ordinary provider chats.
Prepare a useful support report
Open Settings → Diagnostics. Include the Helios version, Linux release, provider CLI version, expected behaviour, actual result and a minimal sequence that reproduces it. Add a short relevant log excerpt after checking it for credentials, private prompts and personal paths.
Use GitHub Issues for a reproducible defect or Discussions for usage questions. Report a vulnerability through the private security channel.