FlatQL desktop app for macOS, Windows and Linux

The same workbench as the web, packaged so that queries run from your computer and cluster credentials never leave it. macOS first, then Windows and Linux.

Note The desktop app is coming soon and is not downloadable yet. The macOS build (Apple silicon) ships first; Windows and Linux follow. This page describes what the app does so you can decide whether to wait for it. Everything else in these docs applies to the web app today.

Why a desktop app#

The web app talks to your cluster from FlatQL's servers, so the cluster must be reachable from the internet. Many clusters are not: they sit on localhost in a dev container, behind a VPN, or on a private subnet with no public endpoint. The desktop app runs the FlatQL backend and the embedded SQL engine on your machine, so it reaches whatever your machine can reach, with no tunnel and nothing installed on the cluster.

Same account, same team#

You sign in with your FlatQL account, by email and password or with Google. The account, team, plan and role are mirrored locally, so plan limits, grants and the Pro licence behave exactly as on the web. Team management, billing, the shared query history, usage and Ask FlatQL are forwarded to flatql.com; statements you run locally are recorded locally and pushed to the team's query history.

The app re-checks the account with the server at launch and at least every 30 minutes while open. Signing out on the web, a disabled account or a changed password signs the desktop app out as well. Quitting and reopening keeps you signed in; only Sign out ends the session.

Where credentials live#

Cluster credentials are encrypted in the app's local database. The key that encrypts them is held in the operating system's keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux) under the service name FlatQL Desktop. The keychain holds only that key; the account session is a private file in the app's data folder and is never stored in the keychain.

Every request from the app window to its local backend carries a random per-launch key, and the backend refuses requests without it. Another process or a web page on the same machine cannot use the local API.

Three kinds of connection#

Syncing a connection to the web is a choice per connection and can be reversed. A synced connection can stay private to you or be shared with the team by an owner or admin. Worksheets live in the cloud for synced connections so the web and the desktop app show the same ones.

PIN lock#

Lock the app with ⌘⇧L, the rail button or Account → Lock now. The first lock asks you to set a 4-digit PIN. After 5 wrong PINs, or with Forgot your PIN?, your FlatQL password (checked by the server) opens the app and lets you set a new PIN. The lock survives reloads and restarts. The PIN protects the window; the credentials behind it stay encrypted regardless.

What never leaves the machine#

For This Mac only connections: the cluster URL and credentials, the Query DSL sent, and every result row. FlatQL servers see the statement text and its metrics in the query history, the schema context when you use Ask FlatQL, and the account checks. The security page lists the full inventory.

Data on disk#

On macOS everything lives under ~/Library/Application Support/FlatQL/: the local database and certificates, the session file, logs and window state. Removing that folder removes the local data; the vault key remains in the keychain until you delete it there.

Versions#

The desktop app is at version 0.4.7 as of this writing and installs its own copy of the backend. The web app is at 0.4.2; the changelog tracks both.

Until it ships#

Use the web app at /app for any cluster with a public endpoint, including Elastic Cloud and Amazon OpenSearch Service. For a cluster on a private network, a connection can be configured with an SSH tunnel through a bastion host that FlatQL's servers can reach; see connect a cluster. The OpenSearch GUI page explains what the workbench itself offers once connected.