// getting started

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-service so 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

Making Your First Request

  1. Right-click in the collections sidebar and select New Collection, then New Request
  2. Choose an HTTP method and enter a URL, e.g. https://api.example.com/users
  3. Add headers, query parameters, or a body in the tabs below the URL bar
  4. Click Send — Cancel (or Esc) stops a slow request; each tab cancels only its own request
  5. 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.

Importing Collections

Collection file

  1. Click Import in the collections sidebar header and choose Collection File
  2. Pick an OpenAPI 3.0 / 3.1 or Swagger 2.0 spec (YAML or JSON), a Postman v2.0 / v2.1 collection, an Insomnia export, or a HAR file — the format is detected automatically
  3. Choose where the collection folder is created, then click Import
  4. OpenAPI endpoints get example bodies generated from their schemas; Postman request examples, auth settings, and scripts are preserved

cURL command

  1. Click Import and choose cURL Command, then paste the command

Existing folder

  1. Click Import and choose Existing Folder to open a collection that already lives on disk — for example in a git checkout — in place

Postman Environment

  1. Click Import and choose Postman Environment
  2. All variables are imported into a new Resonance environment

Organising Collections

Right-click in the collections sidebar for these actions:

  • Collection: New Request, New Folder, Run Collection, Manage Variables, Edit Auth, export, 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

Environments & Variables

  1. Open the environment selector dropdown in the sidebar and click Manage Environments…
  2. Click Add Environment, give it a name (e.g. Development), and add key-value pairs such as baseUrl → https://api-dev.example.com
  3. Select the environment from the dropdown to activate it
  4. Use {{variableName}} anywhere in URLs, headers, or request bodies — values are substituted at send time, entirely locally

Dynamic variables like {{$uuid}} and {{$timestamp}} are generated fresh on every request without touching the environment.

Authentication

  1. Open the Authorization tab in the request panel
  2. Choose a type: Bearer Token, Basic Auth, API Key, OAuth 2.0, Digest Auth, NTLM, or AWS Signature v4
  3. Set auth once on a collection or folder (Edit Auth in its context menu) and choose Inherit from Parent on the requests
  4. Credentials are kept in the OS keychain, not in the collection files you commit
  5. 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

  1. Click + in the tab bar to open a new workspace tab
  2. Each tab holds its own URL, method, headers, body, and response state independently
  3. Switch tabs with Ctrl/Cmd+1–9; open a new one with Ctrl/Cmd+T
  4. 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:

  • 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-stream with 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

  • Press ? anywhere to open the shortcuts reference
  • Ctrl/Cmd+Enter — Send request
  • Esc — Cancel the running request, or disconnect an open stream
  • Ctrl/Cmd+S — Save current endpoint
  • Ctrl/Cmd+T — New workspace tab
  • Ctrl/Cmd+W — Close current tab
  • Ctrl/Cmd+, — Open settings

Exporting Code

  1. Right-click an endpoint or use the export button and select Export Code
  2. Choose from cURL, Python, JavaScript (Fetch or Axios), Node.js, Go, PHP, Ruby, or Java
  3. The generated snippet copies to your clipboard

Next Steps

  • Collection Runner — run sequences of requests and chain variables between steps
  • 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