> For the complete documentation index, see [llms.txt](https://docs.sesori.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sesori.com/help/troubleshooting.md). # Troubleshooting Most problems come from an offline Bridge, mismatched Sesori accounts, a local folder the Bridge cannot access, or an assistant that is missing or not authenticated. ## Quick checks 1. Start the Bridge on the computer that holds your code: ```bash sesori-bridge ``` 2. Confirm the app and Bridge use the same Sesori account. 3. Keep the computer awake, online, and the Bridge process running. 4. Open **Settings → Harnesses** and confirm the selected assistant is ready and enabled. 5. Refresh the project or session. ## Connection and sign-in ### Bridge command not found Install or refresh the Bridge: {% tabs %} {% tab title="macOS or Linux" %} ```bash curl -fsSL https://sesori.com/install.sh | bash ``` Open a new terminal. If the launcher is still unavailable, run: ```bash ~/.local/share/sesori/bin/sesori-bridge ``` {% endtab %} {% tab title="Windows" %} ```powershell irm https://sesori.com/install.ps1 | iex ``` Open a new PowerShell window. If `PATH` has not refreshed, run: ```powershell & "$env:LOCALAPPDATA\sesori\bin\sesori-bridge.exe" ``` {% endtab %} {% endtabs %} If Node.js is installed, `npx @sesori/bridge` is another way to install or refresh the Bridge. It does not start the service; run `sesori-bridge` afterward. ### Bridge offline The app can reach the relay, but the relay cannot see the Bridge process. Check whether: * The terminal running `sesori-bridge` was closed. * The computer slept or a laptop lid was closed. * The computer lost internet access. * The Bridge was signed out. * A firewall, VPN, proxy, or corporate network blocks outbound relay traffic. The Bridge prevents ordinary idle sleep by default, but it cannot guarantee that a closed laptop stays awake. Start it again after the computer wakes. ### App and Bridge do not pair GitHub, Google, Apple, and email sign-ins can represent different Sesori accounts. Confirm the exact provider and identity on both devices. To choose a different account on the Bridge, clear its saved authentication and restart: ```bash sesori-bridge logout sesori-bridge ``` There is no `sesori-bridge --login` command. ## Assistants ### Harness is missing or needs attention Open **Settings → Harnesses**, select the assistant, and read its status: * **Runtime missing:** use **Install runtime** when offered, or follow [Install a harness](/setup/prepare-your-assistant.md). * **Authentication required:** complete the sign-in locally unless the page offers a phone flow. Codex is the current assistant with phone device login. * **Disabled:** enable it, then return to the project. * **Unavailable / Needs attention:** refresh setup and confirm the command works locally. * **Unsupported Harnesses screen:** update and restart the Bridge. #### Local verification commands | Assistant | Check locally | | ------------ | ------------------------------------------ | | OpenCode | `opencode --help` | | Codex | `codex login status` | | Cursor | `agent status` | | Claude Code | `claude auth status` | | Pi | `pi --version` | | Oh My Pi | `omp --version` | | Hermes Agent | `hermes status` and `hermes acp --version` | If the command works in your interactive shell but Sesori cannot find it, restart the Bridge from that shell so it inherits the current `PATH`. ### Codex device login does not finish Keep Sesori open while completing the displayed device flow. If it expires, return to **Settings → Harnesses → Codex** and start a new attempt. You can also run `codex` on the computer and authenticate locally. ### Hermes is installed but unavailable Sesori needs Hermes Agent 0.20.0 or later with ACP support, a configured provider, and a model with at least a 64K context window. ```bash hermes setup hermes status hermes acp --version ``` Restart the Bridge after changing the Hermes installation or configuration. ## Projects and Git ### No projects appear Tap **Add Project** to browse the connected computer directly. You can select an existing folder or create a new one. Assistant discovery is an alternative and varies by assistant. Open or create a session in the folder locally, then refresh Sesori. ### The Bridge cannot access a folder Confirm that the operating-system user running the Bridge can read the folder. On macOS, grant **Full Disk Access** only to the terminal app or managed Bridge process you actually use: **System Settings → Privacy & Security → Full Disk Access**. Restart the process and retry. ### Project is unavailable The folder was moved, renamed, or deleted on the computer. Restore it at the original path, or use **Hide Project** to remove the stale entry without deleting local data. ### Dedicated workspace is unavailable A dedicated workspace needs a Git repository with an initial commit. It can also fail when Git cannot create the worktree or branch. If you chose **Enable Git** while adding the project but setup was incomplete, inspect the folder locally: Git files may already exist even though the initial commit failed. Finish or repair the repository on the computer before retrying. ### File Changes is empty or unavailable The view needs a Git baseline. Non-Git projects and repositories without an initial commit cannot provide the same diff. A session using the main project folder can also share changes with other local tools or sessions. Binary files and very large diffs are identified but not rendered as normal text. Review them with your local Git tools. ## Sessions and media ### Session does not load Try these in order: 1. Pull to refresh the Session List. 2. Confirm the Bridge is online. 3. Confirm the session's original assistant is ready and enabled. 4. Confirm the project folder and any dedicated worktree still exist. 5. Restart the Bridge. An archived session is intentionally read-only and cannot be reopened for new prompts. ### Image attachment fails * Confirm the selected assistant supports prompt attachments. * Use JPEG, PNG, GIF, WebP, or BMP. * Keep all images in the message under the Bridge's combined 5 MiB decoded limit. * Do not combine images with a slash command. * Check photo-library permission for Sesori. Some current app builds incorrectly mention a 50 MB budget. The Bridge transport currently enforces 5 MiB, so use the lower limit until the app message is corrected. ### Voice input fails Voice input needs microphone permission, an authenticated Sesori account, and network access to the transcription service. * Allow microphone access in system settings. * Check the internet connection. * Keep the recording under 15 minutes. * Try a shorter recording or type the prompt while transcription is unavailable. ### Messages remain queued Queued messages wait while the assistant is busy and send in order when the current turn finishes. If the queue does not advance, confirm the Bridge and assistant are still online, then stop or refresh the session. ## Updates and support ### Bridge update does not apply Managed installs check for updates at startup and every four hours. Updates discovered during a run apply after restart: ```bash sesori-bridge update ``` Stop with `Ctrl+C`, then start `sesori-bridge` again. Use `sesori-bridge update --force` only if the updater recommends it. ### Still stuck? Send support: * The phone and Bridge operating systems. * The app and Bridge versions. * The assistant name and its status under **Settings → Harnesses**. * The relevant error and a short, redacted section of Bridge output. * A screenshot with source code, project paths, account details, tokens, and secrets removed. Email , open a [GitHub issue](https://github.com/sesori-ai/sesori_apps_monorepo/issues), or join [Discord](https://discord.gg/5KBC8dV9uR). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sesori.com/help/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.