Start with the symptom, not with a blind restart.
Polystro exposes several operational surfaces because the likely cause of a problem depends on what is actually failing. Use this page to route yourself to the right doc instead of debugging the wrong layer.
How To Use This Page
Choose the section that matches what feels broken right now. If a preview is blank, start with previews and routing. If the wrong model handles a command, start with command routing. If the app is blocked before you even reach the shell, start with licensing and support.
Default rule
Preview and Routing Problems
Preview does not load
Check services and previews first, then use environment and routing to verify the host, port, and overrides.
Wrong local hostname or stale route
Use Routing Overview to see which workstream owns the hostname and which actual port is currently mapped.
Service starts but behavior is wrong
Open the Environment panel and compare diagnostics and diff before assuming the code change is at fault.
Auth works in one tab but not another
Review browser identity mode and integrated browser behavior so you know whether mirror, isolate, or hybrid is expected.
Agents, Commands, and Automations
CLI not detected or auth is failing
Go to CLI Setup and Auth and verify the provider works outside Polystro before expecting the desktop runtime to detect it.
Custom slash command is missing or stale
Open Command Routing and Slash Commands and check the commands folder, imports, and refresh-from-source behavior.
Wrong model handled a command
Inspect the model routing matrix and routing policies rather than changing global model defaults blindly.
Scheduled automation did not run
Confirm the desktop runtime was available and that the automation is enabled, then review automation settings and command routing.
CLI Setup and Auth
Fix detection, login, and API key issues at the provider boundary.
Command Routing and Slash Commands
Debug custom commands, markdown imports, command routing, and policy decisions.
Automation and Remote Access
Review scheduled automations, template-backed runs, and desktop-owned execution expectations.
Account and Device Problems
Device limit reached
Use the account flow to manage devices instead of retrying activation in the desktop app over and over.
License expired or invalid
Review the recovery state and use the correct renewal or activation path before assuming the app installation is bad.
Update prompt confusion
Check the update dialog for release notes, current version, latest version, and install state.
Need to send logs to support
Use the built-in bug report flow so support gets system information, recent logs, and trace IDs with the report.
Still Stuck
If you have already checked the right surface and the problem still does not make sense, capture the context rather than randomizing the environment further. Note the workstream, routed host, CLI, and the exact state that reproduced the issue.
Then send a bug report with the built-in report flow so the desktop logs and trace IDs travel with the issue.