Add remote CLIProxyAPI connection settings

README.md

@@ -84,6 +84,19 @@ Quota checks refresh once a minute while the popup is open. Manual Refresh bypas
 
 ### Bring your own backend
 
+To connect to an existing server, open **Settings → Connection → Remote**.
+Enter its base URL (without `/v1`), management key, and optionally a client API
+key for model discovery, then choose **Test and save connection**. No local
+CLIProxyAPI installation is required. Accounts and quotas use the management
+key; provider OAuth credentials remain on the server.
+
+Use HTTPS, or loopback HTTP through an existing SSH tunnel. Remote mode shows
+connection health instead of local service controls. Add new accounts through
+**Manage accounts**, which opens the server's management panel. See
+[remote configuration](docs/configuration.md#remote-connections) for details.
+
+For a custom **local executable**:
+
 ```bash
 python3 ~/.config/omarchy/plugins/soojy.omaproxy/scripts/omaproxy.py setup \
   --binary /absolute/path/to/cli-proxy-api-plus

SECURITY.md

@@ -13,6 +13,13 @@ only the reviewed flat regular-file archive layout is accepted. See the
 [installer trust policy](docs/installer-security.md). The proxy engine and upstream provider endpoints are separate trust
 boundaries.
 
+Remote connections use a user-selected HTTPS server (normal TLS verification)
+or loopback HTTP, such as an SSH tunnel. Remote keys are stored separately from
+local backend settings, with mode 0600. The management key grants access to the
+server's accounts and configuration; provider tokens remain on that server.
+Authenticated requests reject redirects, bypass environment proxies, and bound
+response size. Remote mode does not execute local backend/service commands.
+
 Email labels are blurred by default and reveal on click; closing the popup hides them again. The concealed view blurs a fixed placeholder rather than the real address. Inline logs redact email addresses. It does not encrypt
 credentials, alter the backend, or redact files exported outside the plugin.
 Copy API key intentionally places a secret on the clipboard, where a clipboard

docs/configuration.md

@@ -7,6 +7,8 @@
 | `~/.config/omarchy/plugins/soojy.omaproxy/` | Installed shell plugin |
 | `~/.config/omaproxy/config.yaml` | Backend configuration |
 | `~/.config/omaproxy/settings.json` | Bridge settings and local keys, mode 0600 |
+| `~/.config/omaproxy/connection.json` | Selected connection mode and remote URL/keys, mode 0600 |
+| `~/.config/omaproxy/remote-state/` | Separate quota cache and authentication error state for each remote connection |
 | `~/.config/omaproxy/auth/` | Provider credentials, private directory |
 | `~/.config/omaproxy/quotas.json` | Private cached quota readings |
 | `~/.config/omaproxy/oauth-session.json` | Private pending browser sign-in session |
@@ -30,6 +32,53 @@ systemctl --user status omaproxy.service
 journalctl --user -u omaproxy.service
 ```
 
+## Remote connections
+
+In **Settings → Connection → Remote**, enter a server base URL such as
+`https://proxy.example.com` or `https://proxy.example.com/prefix`. Do not include
+`/v1`, `/v0/management`, or `/management.html`: OmaProxy appends those paths.
+URLs containing credentials, query parameters, or fragments are rejected.
+
+Supply the server's **management key**. The optional **client API key** enables
+model discovery and copying the client key for coding tools. Choose **Test and
+save connection** to validate access before changing the active connection.
+Blank key fields reuse saved values only when the server URL is unchanged.
+To switch to management-only access, select **Remove saved client API key** and
+then **Test and save connection**. This retains the management key.
+Keys never appear in saved shell settings or status output; input is sent to
+Python over stdin and stored privately in `connection.json`.
+
+Direct remote management requires the server's `remote-management.allow-remote`
+setting and management secret to be configured for remote access. HTTPS uses
+normal certificate verification. Alternatively, use an existing SSH tunnel,
+for example forwarding a free laptop port to the server's loopback port:
+
+```bash
+ssh -N -L 127.0.0.1:18317:127.0.0.1:8317 user@server
+```
+
+Then connect OmaProxy to `http://127.0.0.1:18317`. OmaProxy does not manage the
+tunnel. HTTP is accepted only for loopback addresses. Requests do not follow
+redirects or use environment HTTP proxies.
+
+Accounts, quotas, models, account enablement, API-key providers, and routing use
+the selected server. Changes affect its other clients too. **Manage accounts**
+opens the server's panel for new-account sign-in; sign in with your server's
+management key. Native remote OAuth is not yet supported.
+
+Local start/stop/restart, autostart, configuration-file editing, and journal logs
+are unavailable in remote mode. Selecting Remote does not install a binary or
+change a local service. Selecting Local restores the saved local configuration;
+existing installations without `connection.json` continue using Local.
+
+Remote caches are separated by URL and credentials. Changing connections cannot
+write an old refresh into the new connection's cache. If the management key is
+rejected, automatic management requests stop until the connection is tested and
+saved again. Rejected client keys stop model polling without hiding accounts or
+quotas. No keys or remote details belong in GitHub reports.
+
+## Removal
+
 To remove the integration while retaining credentials:
 
 ```bash