Troubleshooting Sesori: Bridge and connection issues

Fix Bridge, assistant, and connection issues for Sesori with OpenCode, Codex, and Cursor on macOS, Linux, and Windows.

Most Sesori issues come from one of three places: your assistant is not ready, the Bridge is not running, or the app and Bridge are signed into different accounts.

Quick checks

Start here:

1. Open a terminal on your laptop or desktop.
2. Confirm your assistant is installed — run whichever applies:

   opencode --help        # OpenCode
   codex --version        # Codex
   cursor-agent --version # Cursor

   Per-assistant setup status is also visible in the app under Settings → Harnesses.
3. Start the Bridge:

   sesori-bridge

4. Sign into the Bridge with GitHub, Google, Apple, or email.
5. Open Sesori and sign in with the same account.

Bridge offline

Sesori shows Bridge Offline when the app can reach the relay, but the relay cannot see the Bridge process running on your machine.

Common causes:

• The terminal running sesori-bridge was closed.
• Your laptop or desktop went to sleep.
• Your machine lost internet access.
• The Bridge was signed out.
• A firewall, VPN, or corporate network is blocking outbound relay traffic.

Fix it:

sesori-bridge

Keep that terminal open while you use Sesori.

Sign-in does not connect

Use the same provider and account in both places.

If the app is signed in with Google and the Bridge is signed in with GitHub, they will not match. Sign out and sign back in with the same account.

To force the Bridge to sign in again, clear the stored token and restart:

sesori-bridge logout
sesori-bridge

The Bridge asks you to sign in automatically whenever it starts without a valid stored token, so clearing it and starting again is all you need.

Assistant not found

If the Bridge cannot start your assistant, confirm its command works:

opencode --help        # OpenCode
codex --version        # Codex
cursor-agent --version # Cursor

If the command fails, install the assistant again or fix your PATH.

If the assistant is installed in a custom location, point the Bridge to it:

sesori-bridge --opencode-bin /path/to/opencode
sesori-bridge --codex-bin /path/to/codex
sesori-bridge --cursor-bin /path/to/cursor-agent

For OpenCode and Codex, an explicit path is trusted as-is — the Bridge skips the version check it would otherwise run on a binary found through your PATH. Cursor is version-checked either way.

If the Bridge finds the binary but the version is too old, you'll see a message like:

Installed OpenCode 1.13.0 is older than the minimum supported 1.14.0; using the existing managed OpenCode 1.18.11 instead.

If no usable runtime is found at all:

OpenCode runtime setup failed: No usable existing OpenCode runtime was found. Install OpenCode locally and retry: https://opencode.ai/docs#install

The Bridge starts in a degraded state and retries in the background rather than exiting, so you can fix the issue without restarting the Bridge.

Cursor: authentication required

If Cursor is installed but the Bridge reports authentication required, Cursor is not logged in on this machine.

Check the status:

cursor-agent status

If it shows you're not logged in, authenticate:

cursor-agent login

Alternatively, set the CURSOR_API_KEY environment variable before starting the Bridge. Once authenticated, the Bridge will pick up Cursor automatically on the next retry.

Port already in use

The Bridge starts OpenCode on a local port (a numbered "channel" your computer uses for network traffic). If you've pinned a specific port and another program on your machine is already using it, either close that program or tell the Bridge to use a different port with --opencode-port. For example:

sesori-bridge --opencode-port 4097

You can pick almost any number between 1024 and 65535 that isn't already in use.

If another Bridge process is running, stop it:

pkill sesori-bridge

Then start the Bridge again.

No projects

Projects come from your assistant. Open a project folder on your laptop or desktop in your assistant first, then refresh the Sesori project list.

Project directory not found

This means the folder behind a project was renamed, moved, or deleted on your machine.

Fix it by opening the correct folder in your assistant again, then refresh Sesori.

Session will not load

Try these in order:

1. Pull to refresh the Session List.
2. Confirm the Bridge is still running.
3. Confirm your assistant still has access to the project directory.
4. Restart the Bridge.

Voice input fails

Voice input needs microphone permission and network access to the transcription service.

Fix it:

• Allow microphone access for Sesori in your system settings.
• Keep recordings shorter than the current limit.
• Check your internet connection.
• Try typing the prompt if transcription is temporarily unavailable.

Messages are queued

Queued messages are normal when your assistant is already busy. Sesori sends them in order once the current task finishes.

If you want to interrupt the flow:

• Tap Stop to abort the running task.
• Tap Send now on a queued message.
• Tap Cancel to remove a queued message.

Still stuck?

Send us:

• What platform you're using.
• Which assistant you're using and whether it runs locally.
• The last few lines from the sesori-bridge terminal.
• A screenshot of the Sesori error state.

Email [email protected] or use Discord.