> 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/setup/set-up-the-bridge.md).

# Install, configure, and run the Bridge

Install, configure, update, and run the Sesori Bridge CLI on macOS, Linux, or Windows.

The Sesori Bridge runs beside your code and AI coding assistants. It connects them to the mobile app through Sesori's encrypted relay.

The packaged Bridge supports macOS, Linux, and Windows on x64 and arm64 computers.

## 1. Install the Bridge

{% hint style="warning" %}
The convenience commands below download and immediately execute a Sesori-owned installer. The installer verifies the downloaded Bridge archive, but the installer script itself still depends on the HTTPS download and Sesori's publishing account. Review the [Unix installer](https://github.com/sesori-ai/sesori_apps_monorepo/blob/main/install.sh) or [Windows installer](https://github.com/sesori-ai/sesori_apps_monorepo/blob/main/install.ps1) first, or use the inspect-before-running steps below when your security policy requires it.
{% endhint %}

{% tabs %}
{% tab title="macOS or Linux" %}

```bash
curl -fsSL https://sesori.com/install.sh | bash
```

The installer places the Bridge under `~/.local/share/sesori/` and creates the launcher `~/.local/bin/sesori-bridge`. It may add `~/.local/bin` to a Bash, Zsh, or Fish profile when that directory is not already on `PATH`.
{% endtab %}

{% tab title="Windows" %}
Open PowerShell and run:

```powershell
irm https://sesori.com/install.ps1 | iex
```

The installer places the Bridge under `%LOCALAPPDATA%\sesori\` and adds its `bin` directory to your user `PATH`.
{% endtab %}
{% endtabs %}

### Inspect the installer before running

These steps download the same installer to the current directory so you can review the exact file before executing it:

{% tabs %}
{% tab title="macOS or Linux" %}

```bash
curl -fsSL https://sesori.com/install.sh -o sesori-install.sh
less sesori-install.sh
bash sesori-install.sh
rm sesori-install.sh
```

{% endtab %}

{% tab title="Windows" %}

```powershell
Invoke-WebRequest https://sesori.com/install.ps1 -OutFile .\sesori-install.ps1
Get-Content .\sesori-install.ps1
& .\sesori-install.ps1
Remove-Item .\sesori-install.ps1
```

{% endtab %}
{% endtabs %}

If PowerShell policy blocks the reviewed local script, follow your organization's execution policy rather than lowering it solely for this installation.

### Install with npm

If Node.js is installed, npm can bootstrap or refresh the same managed Bridge installation:

```bash
npx @sesori/bridge
```

`npx @sesori/bridge` installs the Bridge but does not start it or pass Bridge arguments to it. Run `sesori-bridge` after the installer finishes. The bootstrap itself accepts `--force` (`-f`) to reinstall and `--help` (`-h`) to show its options.

`npx` resolves code from the npm registry at execution time. Review the [`@sesori/bridge` package](https://www.npmjs.com/package/@sesori/bridge) and use an approved version when your environment requires reproducible installation.

### Verify the installation

Open a new terminal, then run:

```bash
sesori-bridge --version
```

If the command is not found, run the managed binary directly:

{% tabs %}
{% tab title="macOS or Linux" %}

```bash
~/.local/share/sesori/bin/sesori-bridge --version
```

{% endtab %}

{% tab title="Windows" %}

```powershell
& "$env:LOCALAPPDATA\sesori\bin\sesori-bridge.exe" --version
```

{% endtab %}
{% endtabs %}

## 2. Start and sign in

```bash
sesori-bridge
```

On first run, choose GitHub, Google, Apple, or email sign-in. OAuth options open or print a browser URL; email sign-in continues in the terminal. The Bridge then registers with the relay, checks the harnesses on this computer, and waits for the app.

There is no `--login` option. To change accounts, run `sesori-bridge logout`, then start the Bridge again.

## 3. Keep it running

The Bridge is a foreground process. It and the computer must remain running, awake, and online for remote sessions to work. The Bridge prevents ordinary idle sleep by default, but closing a laptop lid can still put the computer to sleep.

Press `Ctrl+C` to stop the Bridge cleanly.

## 4. Check the connection

Open Sesori and sign in with the same account. The Bridge indicator turns green when the app can reach it. If it remains offline, use [Troubleshooting](/help/troubleshooting.md).

## Bridge CLI commands

The `run` command is the default, so `sesori-bridge` and `sesori-bridge run` both start the Bridge.

### Everyday commands

| Command                               | Purpose                                                                    |
| ------------------------------------- | -------------------------------------------------------------------------- |
| `sesori-bridge`                       | Start the Bridge and sign in if needed                                     |
| `sesori-bridge --version`             | Print the installed version                                                |
| `sesori-bridge --help` (`-h`)         | Show the global command overview                                           |
| `sesori-bridge run --help`            | Show run and harness-specific options                                      |
| `sesori-bridge logout`                | Clear saved Sesori authentication                                          |
| `sesori-bridge update`                | Install the latest eligible release on the configured track, then exit     |
| `sesori-bridge update --force` (`-f`) | Reinstall the latest release on the track, even if it is already installed |

### Configuration commands

| Command                                     | Purpose                                                   |
| ------------------------------------------- | --------------------------------------------------------- |
| `sesori-bridge config plugins`              | List harness plugins and whether each is eligible         |
| `sesori-bridge config plugins enable <id>`  | Enable a harness plugin; restart the Bridge to apply      |
| `sesori-bridge config plugins disable <id>` | Disable a harness plugin; restart the Bridge to apply     |
| `sesori-bridge config yolo`                 | Show whether Bridge-wide automatic approval is enabled    |
| `sesori-bridge config yolo off`             | Restore permission prompts                                |
| `sesori-bridge config track`                | Show the current release track                            |
| `sesori-bridge config track stable`         | Follow public stable releases                             |
| `sesori-bridge config track internal`       | Follow stable and Sesori internal prereleases             |
| `sesori-bridge config edit`                 | Open the Bridge configuration file in your default editor |

Valid plugin IDs are `opencode`, `codex`, `copilot`, `cursor`, `claude`, `hermes`, `pi`, `omp`, `deepseek`, and `grok`.

{% hint style="danger" %}
Bridge-wide YOLO mode approves every permission request without sending it to a connected client. Harness-specific bypass or auto-approval settings can remove additional safeguards. This setup guide does not recommend enabling either; read [Security and privacy](/get-started/security-and-privacy.md) before changing approval policy.
{% endhint %}

The public release track is `stable`. The `internal` track is for Sesori development builds and is not recommended for normal use.

### Run options

| Option                | Default                        | Purpose                                                     |
| --------------------- | ------------------------------ | ----------------------------------------------------------- |
| `--data-dir <path>`   | Platform Sesori data directory | Override account-bound tokens, Bridge ID, and database data |
| `--log-level <level>` | `info`                         | Set `verbose`, `debug`, `info`, `warning`, or `error` logs  |

Diagnostic logs go to stderr. Sign-in prompts, authorization links, and startup status remain visible on stdout at every log level.

{% hint style="danger" %}
`run --help` also exposes custom relay, authentication-backend, and debug-server options for controlled development. Do not use them for normal setup. A custom authentication backend receives sign-in credentials and tokens; a custom relay participates in public-key delivery and sees routing metadata. Use only endpoints you operate or trust over `https://` and `wss://`, except for isolated loopback development. The debug server has no authentication, is accessible to other local processes, and must never be forwarded or exposed.
{% endhint %}

Every harness also accepts a binary override:

| Harness        | Options                                       |
| -------------- | --------------------------------------------- |
| OpenCode       | `--opencode-bin` and the server options below |
| Codex          | `--codex-bin`, `--codex-port`                 |
| GitHub Copilot | `--copilot-bin`                               |
| Cursor         | `--cursor-bin`, `--cursor-api-endpoint`       |
| Claude Code    | `--claude-bin`                                |
| Hermes Agent   | `--hermes-bin`                                |
| Pi             | `--pi-bin`                                    |
| Oh My Pi       | `--omp-bin`                                   |
| DeepSeek       | `--deepseek-bin`                              |
| Grok Build     | `--grok-bin`                                  |

Passing a custom binary path makes that local installation authoritative and disables managed installation for that harness. Run `sesori-bridge run --help` for the complete generated option reference.

{% hint style="warning" %}
Use only executables and API endpoints you trust. A custom harness binary runs with the Bridge user's local privileges and can inherit the Bridge environment. A custom Cursor API endpoint also changes where Cursor sends its API traffic.
{% endhint %}

## Advanced: attach to an existing OpenCode server

The recommended default is to let the OpenCode plugin start and manage its own server. External attachment gives the Bridge less control over the server's authentication, transport, and lifecycle. Follow OpenCode's official [server documentation](https://opencode.ai/docs/server/) and keep the server bound to loopback.

{% hint style="danger" %}
An unauthenticated OpenCode server trusts every process that can reach its port. Use the command below only on a trusted single-user computer, keep the server on `127.0.0.1`, and never forward or expose the port.
{% endhint %}

After starting an intentionally unauthenticated loopback server under your own process manager, attach with the namespaced options:

```bash
sesori-bridge --opencode-no-auto-start --opencode-port 4096 --opencode-no-password
```

{% hint style="info" %}
OpenCode options are namespaced for multi-harness support. Use `--opencode-no-auto-start` and `--opencode-port`; the old Bridge options `--no-auto-start` and `--port` are not accepted.
{% endhint %}

### Password-protected attachment

OpenCode supports a server password, and attachment mode accepts the matching value through `--opencode-password`. Sesori does not recommend a password recipe here because the Bridge currently accepts that secret only as a process argument, where another local user may be able to inspect it. There is no fully secret-safe attachment form until the Bridge supports a non-argument credential source. Prefer managed mode when local-process trust is a concern.

The default host is `127.0.0.1`. Keep direct attachment on loopback: OpenCode uses HTTP, and Basic authentication does not encrypt the password or session traffic. To reach OpenCode on another computer, use an encrypted tunnel and attach the Bridge to the tunnel's loopback endpoint rather than exposing the server directly.

In managed mode, setting `--opencode-host 0.0.0.0` exposes the Basic-auth server to the local network and has the same transport limitation. Never expose an unauthenticated OpenCode server to a network.

An attached server remains externally managed. Sesori can refresh its setup status, but it will not start, stop, restart, suspend, or clean up that OpenCode process.

## Configuration file

`sesori-bridge config edit` opens `~/.config/sesori/config.json`. Relevant settings include sleep prevention, Bridge-wide YOLO mode, and the release track:

```json
{
  "sleepPrevention": "always",
  "yolo": false,
  "releaseTrack": "stable"
}
```

You can also configure plugin idle timeouts. Plugin-specific values override `default`; omitted values use 45 minutes, and zero means never idle-stop:

```json
{
  "plugins": {
    "disabled": ["cursor"],
    "default": {"idleTimeoutMins": 30},
    "opencode": {"idleTimeoutMins": 0}
  }
}
```

Prefer the app or the `config` commands for settings they expose. Restart the Bridge after changing plugin eligibility, YOLO mode, or the release track.

## Updates

Managed installations check for updates at startup and every four hours while running. An update discovered during a run is applied after the Bridge restarts. Check and install immediately with:

```bash
sesori-bridge update
```

Use `sesori-bridge update --force` for a repair or when the updater recommends reinstalling. It reinstalls the latest release for the selected track and can move an internal build back to stable when the configured track is `stable`.

Automatic checks are skipped in CI or when `SESORI_NO_UPDATE=1` is set. The shell and npm installers always install the latest stable release, regardless of the configured track.

## Remove the managed installation

First stop every running Bridge instance, then attempt to unregister this Bridge and clear its saved authentication:

```bash
sesori-bridge logout
```

If you started the Bridge with `--data-dir <path>`, stop that process and instead run `sesori-bridge logout --data-dir <path>`. Verify and remove the custom account-data directory separately, in addition to removing the managed installation shown below.

{% hint style="danger" %}
The commands below delete the entire local Sesori data directory, not just the executable. This removes the Bridge ID, authentication, managed harness runtimes and state, local project and session catalog, and locally stored chat history. It does not delete your repositories; harness data stored outside Sesori's directories remains.
{% endhint %}

Delete the managed installation and, on macOS or Linux, its launcher:

{% tabs %}
{% tab title="macOS or Linux" %}

```bash
rm -rf ~/.local/share/sesori
rm -f ~/.local/bin/sesori-bridge
```

{% endtab %}

{% tab title="Windows" %}

```powershell
$sesoriBin = "$env:LOCALAPPDATA\sesori\bin"
$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
$newPath = (($userPath -split ';' | Where-Object { $_ -and $_.TrimEnd('\') -ine $sesoriBin.TrimEnd('\') }) -join ';')
[Environment]::SetEnvironmentVariable('PATH', $newPath, 'User')
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\sesori"
```

{% endtab %}
{% endtabs %}

Open a new terminal after removing the Windows `PATH` entry. On macOS or Linux, the installer may have added a generic `~/.local/bin` entry to a shell profile; the commands above leave it in place because other tools may use that directory. Remove that profile line manually only when it is no longer needed. The configuration file under `~/.config/sesori/` remains unless you remove it separately. Removing the npm package alone does not remove the managed Bridge directory.

Prompt attachment files use a separate shared directory and are not removed by these commands: `~/Library/Application Support/Sesori Attachments` on macOS; `$XDG_DATA_HOME/sesori-attachments` on Linux when `XDG_DATA_HOME` is absolute, otherwise `~/.local/share/sesori-attachments`; and `%LOCALAPPDATA%\Sesori Attachments` on Windows. Delete that directory only when no other Bridge data directory references its files.

## Next

👉 [Connect the app and Bridge](/setup/connect-the-app.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sesori.com/setup/set-up-the-bridge.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.