Getting Started
Resonance is a local-first, zero-account desktop API client. Nothing leaves your machine unless you send a request. No sign-in, no telemetry, no cloud sync — just install and start building.
Installation
Linux
- Download the AppImage or .deb from the Download section, or install from Flathub (
flatpak install flathub io.github.db_mobile.resonance), Snap (snap install db-mobile-resonance), or the AUR (yay -S resonance-bin) - AppImage: make it executable (
chmod +x Resonance*.AppImage) and run it - .deb: install with
sudo dpkg -i resonance*.deb - Snap: after installing, run
snap connect db-mobile-resonance:password-manager-serviceso secrets are stored in the OS keychain — without this connection the strict snap falls back to unencrypted local storage
macOS
- Download the DMG (universal — Intel and Apple Silicon) or install via Homebrew:
brew install db-mobile/resonance/resonance - Open the DMG and drag Resonance to your Applications folder
Windows
- Download the NSIS installer and run it — no elevated permissions required
Command line
- For CI and servers there is a separate
resonancebinary with no desktop dependencies:curl -fsSL https://raw.githubusercontent.com/db-mobile/resonance/main/install.sh | shon Linux and macOS, a.zipfor Windows, or a GitHub Action. See Command Line & CI
Making Your First Request
- Right-click in the collections sidebar and select New Collection, then New Request
- Choose an HTTP method and enter a URL, e.g.
https://api.example.com/users - Add headers, query parameters, or a body in the tabs below the URL bar
- Click Send — Cancel (or
Esc) stops a slow request; each tab cancels only its own request - Inspect the response — Body, Headers, Cookies, and Performance tabs are all available. Error responses (4xx/5xx) are kept in the tab just like successful ones
Bodies are sent for every method except GET and HEAD, so a DELETE or OPTIONS request can carry one. See Requests & Responses for body types, response preview, JSONPath/XPath inspection, schema validation, and history.
Importing Collections
Collection file
- Open the main menu (☰) at the top of the sidebar, choose Import and then Collection or Environment File — or press
Ctrl/Cmd+O - Pick an OpenAPI 3.0 / 3.1 or Swagger 2.0 spec (YAML or JSON), a Postman v2.0 / v2.1 collection, an Insomnia v4 (JSON) or v5 (YAML) export, a HAR file, or a Postman or Insomnia environment export — the format is detected automatically
- Choose where the collection folder is created, then click Import
- OpenAPI endpoints get example bodies and response schemas from the spec; Postman request examples, auth settings, and scripts are preserved; environments in an Insomnia export are imported too
- An environment file creates environments instead of a collection and ignores the destination folder: secret (Postman) and confidential (Insomnia) variables go to the OS keychain, disabled Postman variables are skipped, an Insomnia sub-environment inherits its base environment, and a name that already exists gets a numeric suffix
cURL command
- Click Import and choose cURL Command, then paste the command — a live preview shows the parsed request
- Name the request and pick the collection to add it to (or create a new one)
Existing folder
- Click Import and choose Existing Folder to open a collection that already lives on disk — for example in a git checkout — in place
Organising Collections
Right-click in the collections sidebar for these actions:
- Collection: New Request, New Folder, Run Collection, Manage Variables, Edit Auth, Export as OpenAPI (JSON or YAML), Generate Documentation, Rename, Delete (or Close for a collection opened in place)
- Folder: New Request (created inside the folder), New Subfolder, Rename Folder, Run Folder, Edit Auth, Delete Folder (removes the folder and the requests in it)
- Request: Pin, Rename, Duplicate (copies the body, headers, parameters, scripts, and stored credentials), Move to Folder… (another folder or the collection root), Delete
Collections that fail to load
A collection that cannot be shown appears as a red row at the bottom of the sidebar with the reason. The row offers what makes sense for the cause:
- Locate… — the folder was moved or renamed: pick its new location (or a folder above it) and the collection comes back with its credentials
- Remove from list — forget a collection that is gone for good; nothing on disk is touched, and you can open it again with Import → Existing Folder
- Retry — after fixing a file (for example invalid YAML), reload the collections
Exporting collections
- Export as OpenAPI writes an OpenAPI 3.0.3 spec with paths, parameters, bodies, and saved responses
- Generate Documentation produces an HTML or Markdown API reference, optionally with example data and code samples in your chosen languages
- Secret values are exported empty;
{{variable}}references are kept. Only HTTP requests are exported
Environments & Variables
- Open the environment selector in the sidebar and click Manage Environments… — or press
Ctrl/Cmd+E - Click New, name the environment (e.g. Development), and give it a Color if you like — it is shown next to the name
- Under Variables, click Add and enter pairs such as
baseUrl → https://api-dev.example.com. Click the lock to make a value secret - Click Set active, or pick the environment from the selector, to use it
- Use
{{variableName}}anywhere in URLs, headers, auth, or request bodies — values are substituted at send time, entirely locally
Edits save as you go. Duplicate, Export, and Delete act on the selected environment; Import and Export All at the bottom of the list move all environments between machines (merge with or replace the existing ones). Import also accepts a file saved with a single environment’s Export. Secret values are exported empty, so re-enter them after importing.
Collection variables
Right-click a collection and choose Manage Variables for values shared by everyone using the collection, stored in the collection folder. When both define the same name, the active environment wins. In the collection runner, values set by scripts and data-file rows take precedence over both.
Variables can reference other variables. A request that still contains unresolved {{names}} is sent as-is, with a warning listing them.
Dynamic variables
Generated fresh on every send (the same value everywhere within one request), without touching the environment. Click Dynamic variables… in either variables dialog for the reference.
{{$uuid}},{{$timestamp}}(seconds),{{$timestampMs}},{{$isoTimestamp}}{{$randomInt:min:max}}(default 0–1000),{{$randomPrice:min:max}},{{$randomBoolean}}{{$randomString:length}}(default 8),{{$randomLoremWords:count}}(default 5){{$randomEmail}},{{$randomName}},{{$randomPhoneNumber}},{{$randomUrl}},{{$randomIPv4}}{{$randomDate:days}},{{$randomDatePast:days}},{{$randomDateFuture:days}}(default 365)
Arguments are optional and separated by colons. Postman-only dynamic variables such as {{$randomFirstName}} are not translated on import.
Authentication
- Open the Authorization tab in the request panel
- Choose a type: Bearer Token, Basic Auth, API Key, OAuth 2.0, Digest Auth, NTLM, or AWS Signature v4
- Set auth once on a collection or folder (Edit Auth in its context menu) and choose Inherit from Parent on the requests
- Credentials are kept in the OS keychain, not in the collection files you commit — see Secrets
- Reference sensitive values via variables:
{{token}}— this also works in the OAuth 2.0 token URL, client ID, and secret
OAuth 2.0 token renewal
- Click Get Token once; the token, its expiry, and any refresh token are stored with the auth settings
- Before a request is sent, a token that expires within 30 seconds is renewed automatically — with the refresh token if there is one, otherwise by repeating a client-credentials or password grant
- The new token is saved where the auth is configured (request, folder, or collection); the collection runner renews the same way
- An authorization-code token without a refresh token cannot be renewed automatically — you are warned, and Get Token fetches a new one
Workspace Tabs
- Click + in the tab bar to open a new workspace tab
- Each tab holds its own URL, method, headers, body, and response state independently
- Switch tabs with
Ctrl/Cmd+1–9; open a new one withCtrl/Cmd+T - Tab state persists across application restarts — open exactly where you left off
Scripts
Open the Scripts tab in the request panel to write pre-request or test scripts in JavaScript. See Using Scripts for the full API reference.
Mock Server
Click the Mock Server toolbar action to spin up a local HTTP server backed by your OpenAPI collections. See Mock Server for setup details.
Real-Time Protocols
Beyond REST and GraphQL, Resonance speaks several streaming and messaging protocols natively — each from its own request tab:
- GraphQL — queries, the click-to-build Explorer, and subscriptions
- gRPC — server reflection with unary and streaming calls
- WebSocket — persistent
ws:///wss://connections - MQTT — publish/subscribe with QoS, retain, and wildcards
- Server-Sent Events —
text/event-streamwith auto-reconnect
While a WebSocket, SSE, or gRPC stream is open, the button next to Send reads Disconnect. GraphQL subscriptions send the request’s headers — including auth — in the connection_init message, both as payload.headers and as a top-level Authorization, which covers Hasura- and Apollo-style servers.
Keyboard Shortcuts
Ctrl/Cmd+/— Show the keyboard shortcuts referenceCtrl/Cmd+Enter— Send requestEsc— Cancel the running request, or disconnect an open streamCtrl/Cmd+S— Save requestCtrl/Cmd+L— Focus the URL barCtrl/Cmd+H— Toggle the history sidebarCtrl/Cmd+J— Open the cookie jarCtrl/Cmd+K— Generate a code snippet (cURL and other languages)Ctrl/Cmd+O— Import a collection fileCtrl/Cmd+E— Open the environment managerCtrl/Cmd+,— Open settingsCtrl/Cmd+\— Toggle the side-by-side layoutCtrl/Cmd+T— New workspace tabCtrl/Cmd+W— Close current tabCtrl/Cmd+Tab / Ctrl/Cmd+Shift+Tab— Next / previous workspace tabCtrl/Cmd+1–9— Switch to workspace tab 1–9Alt+1–6— Switch request tab: Path Params, Query Params, Headers, Authorization, Body, Scripts
Press Ctrl/Cmd+/ or choose Keyboard Shortcuts in the main menu for the in-app reference. On macOS the shortcuts use Cmd.
Exporting Code
- Click the code button next to the URL bar (Generate Code Snippet) or press
Ctrl/Cmd+K - Pick a language: cURL, Python (requests), JavaScript (Fetch or Axios), Node.js (https), Go (net/http), PHP (cURL), Ruby (net/http), or Java (HttpClient)
- The snippet uses the request with variables and auth already resolved; click Copy to Clipboard
Next Steps
- Requests & Responses — bodies, inspection, schema validation, and history
- GraphQL — the Explorer and subscriptions
- Settings, Proxy & Certificates — networking, mTLS, secrets, and updates
- Collection Runner — run sequences of requests and chain variables between steps
- Command Line & CI — run collections and runners headlessly in your pipeline
- Using Scripts — full pre-request and test script API reference
- Mock Server — serve OpenAPI-backed responses locally
- gRPC — reflection, streaming, metadata, and trailers
- Issue tracker — report bugs or request features