// 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

Command line

  • For CI and servers there is a separate resonance binary with no desktop dependencies: curl -fsSL https://raw.githubusercontent.com/db-mobile/resonance/main/install.sh | sh on Linux and macOS, a .zip for Windows, or a GitHub Action. See Command Line & CI

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. See Requests & Responses for body types, response preview, JSONPath/XPath inspection, schema validation, and history.

Importing Collections

Collection file

  1. Open the main menu (☰) at the top of the sidebar, choose Import and then Collection or Environment File — or press Ctrl/Cmd+O
  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 v4 (JSON) or v5 (YAML) export, a HAR file, or a Postman or Insomnia environment export — the format is detected automatically
  3. Choose where the collection folder is created, then click Import
  4. 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
  5. 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

  1. Click Import and choose cURL Command, then paste the command — a live preview shows the parsed request
  2. Name the request and pick the collection to add it to (or create a new one)

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

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

  1. Open the environment selector in the sidebar and click Manage Environments… — or press Ctrl/Cmd+E
  2. Click New, name the environment (e.g. Development), and give it a Color if you like — it is shown next to the name
  3. Under Variables, click Add and enter pairs such as baseUrl → https://api-dev.example.com. Click the lock to make a value secret
  4. Click Set active, or pick the environment from the selector, to use it
  5. 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

  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 — see Secrets
  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:

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

  • Ctrl/Cmd+/ — Show the keyboard shortcuts reference
  • Ctrl/Cmd+Enter — Send request
  • Esc — Cancel the running request, or disconnect an open stream
  • Ctrl/Cmd+S — Save request
  • Ctrl/Cmd+L — Focus the URL bar
  • Ctrl/Cmd+H — Toggle the history sidebar
  • Ctrl/Cmd+J — Open the cookie jar
  • Ctrl/Cmd+K — Generate a code snippet (cURL and other languages)
  • Ctrl/Cmd+O — Import a collection file
  • Ctrl/Cmd+E — Open the environment manager
  • Ctrl/Cmd+, — Open settings
  • Ctrl/Cmd+\ — Toggle the side-by-side layout
  • Ctrl/Cmd+T — New workspace tab
  • Ctrl/Cmd+W — Close current tab
  • Ctrl/Cmd+Tab / Ctrl/Cmd+Shift+Tab — Next / previous workspace tab
  • Ctrl/Cmd+1–9 — Switch to workspace tab 1–9
  • Alt+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

  1. Click the code button next to the URL bar (Generate Code Snippet) or press Ctrl/Cmd+K
  2. Pick a language: cURL, Python (requests), JavaScript (Fetch or Axios), Node.js (https), Go (net/http), PHP (cURL), Ruby (net/http), or Java (HttpClient)
  3. The snippet uses the request with variables and auth already resolved; click Copy to Clipboard

Next Steps