SQLly on a page: relay proxy mode

functional

Run the browser build against your own databases through a relay you control - it holds the credentials, so the page never sees a password.

The browser build of SQLly normally runs against sample data in your tab, because a web page cannot open a database socket. Relay proxy mode gives it real servers: a sqlly-relay you run is handed a credential file, and the browser build, opened with that relay's address, then queries every server and database in the file - the object explorer, IntelliSense, execution plans, and row editing all included - while the passwords never leave the relay host.

Who this is for. A team that wants a zero-install SQLly on a page - an internal portal, a support console, a classroom - against a fixed set of databases that an admin controls. It is not the desktop app's Via Relay path: that one is end-to-end encrypted so the relay cannot read your traffic. Here the relay is deliberately the one holding the credentials, so a browser tab never has to.

How it fits together

browser (SQLly on a page)  --wss-->  sqlly-relay proxy  --local-->  SQLly engine  --TDS / PG / MySQL / ...-->  your databases
                                     holds the credential file        one per browser session

The relay serves a credential file. Every connection in it - server, database, login and password, shared logins, SSH tunnels and proxies, and the client, project, and environment labels - is what the browser can reach. Nothing else.
One engine per session. Each browser session gets its own SQLly engine on the relay host, started in a locked-down mode that only opens connections from the file. A request that names its own server or carries its own password is refused.
The browser gets names, not secrets. It receives the connection list with passwords, tunnel settings, and tokens stripped, and it never stores the list - the relay sends it fresh on every page load.
The relay's other job is untouched. The proxy is a separate, opt-in listener. A relay that does not enable it forwards Via Relay traffic exactly as before.

Set up the relay

On a host that can reach the databases and has sqlly-cli installed next to sqlly-relay, write a credential file (export one from the desktop app with File → Export Credentials…, or write it by hand) and start the relay with the proxy flags added to its usual configuration:

sqlly-relay \
  --tls-cert /certs/relay.crt --tls-key /certs/relay.key \
  --proxy-credentials /etc/sqlly/browser-connections.json \
  --proxy-token 'a-long-random-secret' \
  --proxy-bind 0.0.0.0:8444 \
  --proxy-allowed-origins https://sqlly.app

Flag	What it does
`--proxy-credentials`	The credential file. Setting it is what turns the proxy on. The file is re-read for every new browser session, so edits take effect without a restart.
`--proxy-token`	A shared secret the browser must present. Required: without it the relay refuses to start unless you pass `--proxy-insecure-no-token`, which serves every listed database to anyone who can reach the port.
`--proxy-bind`	Where the proxy listens; the default is port 8444. It uses the relay's TLS certificate for `wss://`; `--proxy-plain` serves `ws://` for local testing or behind a TLS-terminating reverse proxy.
`--proxy-allowed-origins`	Comma-separated web origins allowed to open a session, so only pages you host can use the proxy. Leave it out to allow any origin (the token still applies).
`--proxy-max-sessions`	How many browser sessions may be open at once (each is one engine process); the default is 32. A full proxy asks new sessions to try again later.
`--proxy-engine-binary`	Where `sqlly-cli` is, if it is not beside `sqlly-relay` or on the `PATH`.

Every flag has an environment-variable form (RELAY_PROXY_CREDENTIALS, RELAY_PROXY_TOKEN, and so on) for container deployments. The relay container image includes the engine when built with --build-arg WITH_PROXY_ENGINE=1.

Two rules differ from a desktop import: shared logins and tunnel profiles must be defined in the same file (the relay has no saved connections to fall back to), and a via-relay route on a connection is ignored, because the relay host dials every server itself.

Open the browser build against it

Add the proxy address and token to the browser build's URL:

https://sqlly.app/app/?proxy=wss://relay.example.com:8444/proxy&token=a-long-random-secret

A page that embeds the build can set SQLLY_PROXY_URL and SQLLY_PROXY_TOKEN as globals before the app boots instead of putting them in the address bar. On load the app connects, the status line names the relay and how many connections it serves, and those connections appear in the explorer ready to use. The sample databases are not downloaded at all in this mode.

Hosting the page yourself. Browsers only let a page open sockets to origins its security policy allows. The build served at sqlly.app permits its own origin; a proxy on another host needs that policy widened, or serve the build from the relay's own domain. If the page loads but reports that it could not reach the relay proxy, this is the first thing to check.

What changes in the app

Connections are read-only. The list is the relay's list. Add Server, Duplicate, Delete, and Import Connections are disabled; the connection manager's add, remove, and duplicate buttons and its client, project, and environment editors are locked; and opening a connection shows it as View Connection with Save disabled and a note that the relay holds its credentials. Change the credential file on the relay to change what users see.
Test Connection still works - it runs through the proxy like any query - and so do every query feature, the object explorer, IntelliSense catalog sync, execution plans, scripting, and row editing.
Labels come along. Client, project, and environment names, colors, and safety switches from the file group the explorer the same way they do on the desktop; icons are left out to keep the page light.
If the relay goes away, the status line says so and queries on proxied connections fail with a clear message until the page is reloaded.

The wire contract, the engine's proxy mode, and the container build are documented for operators in the repository under docs/remote-relay/browser-proxy.md. For the encrypted desktop path, see Reach your database from anywhere.