Menu

What bonk is

bonk is a local-first desktop API client for HTTP and gRPC, built with Tauri, Svelte and Rust. You open a folder, send requests, and save them as readable *.bonk.json files. Review them in Git like any other source file.

What's inside

  • HTTP: query parameters, headers, auth, JSON, text, form, multipart, binary and GraphQL bodies, formatted responses.
  • gRPC: server reflection or local .proto files, unary and streaming calls, metadata, deadlines, TLS and mTLS.
  • Environments and variables: {{variables}}, globals, named environments, secrets in the OS keychain.
  • Scripts and tests: sandboxed JavaScript with pm.* helpers.
  • Runner and CLI: run a collection in the app, in a terminal or in CI, on the same engine.
  • MCP server: let an AI agent browse, edit and run your workspace.
  • Git: a Source Control tab built into the sidebar.

Offline by default

Editing and organizing a workspace works offline. Sending requests, checking for updates and Git remotes use the network.

Where to go next

Install bonk, then send your first request. To see how files are laid out, read Workspaces as files.

macOS

On Apple Silicon, install with Homebrew:

brew install --cask nekidaz/tap/bonk

Or download the .dmg from GitHub Releases.

Windows

Download the Windows installer (x64) from GitHub Releases and run the setup wizard.

Linux

Download an .AppImage, .deb or .rpm (x64) from GitHub Releases.

# AppImage, from the download directory
chmod +x bonk_*.AppImage
./bonk_*.AppImage

# Debian / Ubuntu
sudo apt install ./bonk_*.deb

Updates

Use Settings → General → Check for updates for signed in-app updates. When an update is available, the update pill lists what's new. Homebrew installs can also use:

brew upgrade --cask bonk

Command line

The bonk CLI is a separate binary for terminals and CI:

brew install nekidaz/tap/bonk

Send and save

  1. Open a folder. An empty directory is enough.
  2. Create an HTTP request. Enter your API URL, for example http://localhost:8080/health.
  3. Send it. Read the status, body, headers and timing in the response pane.
  4. Save it. Press ⌘S on macOS or Ctrl+S on Windows and Linux, then choose a collection folder.

Already have a cURL command? Paste it into the URL bar. Have a collection? Use the import window.

Reuse it with an environment

Add an environment with baseUrl = http://localhost:8080, then change the URL to:

{{baseUrl}}/health

See Variables for globals, secrets and protected environments.

Turn the response into a check

Open Scripts → Tests and add:

pm.test("Service is healthy", () => {
  pm.expect(pm.response).to.have.status(200);
});

Send again and open the Tests response tab. To check a whole collection, open the Runner, choose requests and an environment, and start a run.

Layout

The directory is the source of truth. A folder is a directory, and a request is a <name>.bonk.json file.

payments-api/
├── payments/
│   ├── list-payments.bonk.json
│   └── create-payment.bonk.json
├── auth/
│   └── issue-token.bonk.json
└── grpc/
    └── say-hello.bonk.json

A request file

{
  "name": "List payments",
  "protocol": "http",
  "request": {
    "method": "GET",
    "url": "{{baseUrl}}/v1/payments",
    "headers": {}
  }
}

Folder settings

Collection-level auth lives in .folder.bonk.json. Requests set to inherit use the nearest folder that sets auth. Manual order after drag and drop is saved in the same file. Portable Runner setups go to .bonk/scenarios.json, see Runner.

Git-friendly

Keep requests in the same repository as the API, review changes in a pull request and share the directory with your team. Preferences, history and session state live separately in the platform application-data directory.

Build a request

Set the method and URL, then add query parameters, headers, auth and a body. Supported bodies are JSON, text, form, multipart, binary and GraphQL. The JSON body editor flags syntax errors as you type. Per-request timeout, redirect and TLS overrides are available from the request's actions menu.

Paste a cURL command into the URL bar to turn it into a request. Press ⌘↵ (Ctrl+Enter) to send.

Read the response

The response view shows status, size and timing, formatted JSON, headers and cookies. Search a JSON body or filter it with JSONPath. Large responses open in a read-only viewer with search, folding, line count and Save to file. 4xx and 5xx responses show a hint with quick actions.

Defaults

Settings → Requests applies to every request in the workspace: request timeout, follow redirects, verify SSL certificates (turn off only for local self-signed servers), JSON formatting and response preview size. Proxy and client certificates have their own pages, see Settings.

Code snippets

Generate the request as code in cURL, HTTPie, raw HTTP, C, C#, Go, Java, JavaScript, Node.js, Kotlin, PHP, Python, Ruby, Swift or PowerShell. Open the code panel with ⌘⌥E (Ctrl+Alt+E).

Find the schema

Connect to a server and use reflection, or load local .proto files. In Settings → gRPC you can turn automatic reflection on or off and add .proto import paths (-I). Pick a service and method, and bonk fills in a message template for you to edit.

Make a call

Unary, server-streaming, client-streaming and bidirectional calls are supported. Streams from all four kinds appear in one feed. Set metadata and a deadline per request. The default deadline, maximum message size and default-field display live in Settings → gRPC.

TLS and mTLS

gRPC supports TLS and client certificates, including PKCS#12 (.p12) bundles. Errors are shown in readable form.

Scripts, Runner, CLI, MCP

gRPC requests accept the same scripts as HTTP, and run in the Runner with a gRPC deadline. The CLI and MCP server execute unary calls; streaming keeps its interactive controls in the desktop app.

Auth types

TypeWhat bonk sends
NoneNo auth is added.
BearerAuthorization: Bearer <token>
BasicAuthorization: Basic with base64 of username:password.
API keyA named key, sent as a header or as a query parameter.
OAuth 2.0A token from the keychain, sent as a Bearer token.
SessionSign in once through a Runner scenario; a token per environment, renewed by itself.

An Authorization header you set yourself on the request is not overwritten.

Folder auth and inheritance

A request set to inherit uses the nearest ancestor folder that sets auth, saved in .folder.bonk.json. With no auth anywhere, nothing is sent.

Variables in auth

{{vars}} are resolved before auth is applied, so tokens can come from an environment:

Bearer token: {{token}}

Grants

Choose OAuth 2.0 as the auth type, then one of three grants:

  • Authorization code, with PKCE (S256) on by default.
  • Client credentials.
  • Password.

Settings

FieldNotes
Auth URL, token URL, revoke URLThe auth URL is used by the code grant.
Client ID and secretSent in a Basic header by default, or in the form body.
Scope, audienceScope is space-separated.
Redirect URIEmpty means http://127.0.0.1:<free port>/callback.
Username, passwordFor the password grant.
Auto refreshOn by default.

Every field accepts {{vars}}, so one request can work across environments.

Tokens

Tokens live in the OS keychain, never in workspace files. The token key is a hash of the resolved settings (grant, token URL, client, scope, audience, user), so an environment with its own client gets its own token. bonk renews an expired token before sending and retries once on a 401. The same applies in the app, the Runner, the CLI and MCP.

Set it up

Open a collection's authorization and choose Session. Pick the Runner scenario that signs in (for example Auth · OTP: Login → Send OTP → Verify OTP, where the code is an «ask on send» variable), say which response holds the access token and which the refresh token, and pick the saved request that trades a refresh token for a new access token. Its body reads {{session.refresh}}. Requests of the collection then send Authorization: Bearer {{session.access}}, except the sign-in folder and the renewal request.

How it is kept alive

  • The access token is renewed by itself a minute before it expires (a JWT's exp, or a field like expires_in), and once on a 401.
  • When the refresh token is dead too, the sign-in scenario runs again on its own; only the step that needs a code asks you, in a small form by Send.
  • After you run the sign-in scenario in the Runner, bonk offers Запомнить вход? to keep what it caught.

One session per environment

Signing in to Staging does not touch Production. All sessions lists every environment: who signed in, when the tokens end, renew, sign out. Sessions live in the OS keychain, not in workspace files, git or exports. In the CLI, --env picks the session; a sign-in step needs --input otp=123456.

Using variables

Write {{name}} anywhere in a request:

{{baseUrl}}/v1/payments/{{paymentId}}

Globals and environments

Variables come from globals and from named environments. Edit values inline in the environments sheet (⌘E / Ctrl+E). Mark a variable as secret to keep its value in the OS keychain. Environment names are unique.

A protected environment asks for confirmation before a request is sent to it.

Other sources

  • Dynamic variables such as {{$guid}} give a fresh value on every send.
  • Scripts read and write variables with pm.environment, pm.globals and pm.variables.
  • The Runner turns CSV or JSON rows into variables, one iteration per row.
  • The CLI reads BONK_VAR_<NAME> and --var NAME=VALUE.

CLI precedence

In the CLI, later wins: the app's globals, scenario globals, scenario environment, the --env environment, BONK_VAR_<NAME>, --var, then the data row.

Using them

Type {{$ in a URL, header, body or script editor to get completion, or open the reference dialog and click Insert. The values are generated in Rust at send time.

{
  "id": "{{$guid}}",
  "email": "{{$randomEmail}}",
  "createdAt": "{{$isoTimestamp}}"
}

Catalog

GroupNames
Time$timestamp (Unix seconds), $isoTimestamp (UTC), $randomDateRecent, $randomDatePast, $randomDateFuture, $randomWeekday, $randomMonth
IDs$guid, $uuid, $randomUUID, $randomAlphaNumeric
Numbers$randomInt (0 to 1000), $randomBoolean, $randomSemver, $randomHexColor
Text$randomWord, $randomWords, $randomLoremWord, $randomLoremWords, $randomLoremSentence, $randomLoremParagraph, $randomLoremSlug, $randomColor
People$randomFullName, $randomFirstName, $randomLastName, $randomUserName, $randomPhoneNumber, $randomJobTitle, $randomCompanyName
Internet$randomEmail, $randomExampleEmail, $randomUrl, $randomDomainName, $randomIP, $randomIPV6, $randomUserAgent, $randomPassword
Finance, address, files$randomPrice, $randomCurrencyCode, $randomBankAccountIban, $randomCity, $randomCountry, $randomLatitude, $randomFileName, $randomMimeType and more

The full list is in the reference dialog. $uuid is a synonym of $guid.

Settings → Variables

  • Test data language: English (US) or Russian (KZ) names, addresses and phones.
  • One value per request: {{$guid}} in a header and in the body match. Off gives a new value at every occurrence.
  • Keep substituted values: shown in the response Timeline tab.
  • Repeatable values (seed): the same seed gives the same data on every send and Runner run.

The jar

Set-Cookie headers from responses go into the jar automatically. On the next request, cookies matching the domain and path are added to the Cookie header. Open the jar from the cookie window or the footer chip, and see each response's cookies in the response Cookies tab.

Settings → Cookies

SettingEffect
Store cookies from responsesPut Set-Cookie into the jar.
Send cookies with requestsAdd matching cookies to the Cookie header.
Keep across restartsOn: session cookies survive a restart. Off: they live until bonk closes.
Whose jarPer workspace (a file for each) or shared by the whole app.
Never store for domainsCookies of these domains and their subdomains are neither stored nor sent.

In scripts

Scripts can read cookies with pm.cookies.get(), has() and toObject(), and clear a URL's cookies with pm.cookies.jar().clear(url).

The Scripts tab

Each HTTP or gRPC request has a Scripts tab with two parts: Pre-request runs before sending, Post-response runs after the response. The editor has completion, an outline, Find, folding and Format. Results appear in a Tests / Console panel. Scripts run in an embedded JavaScript sandbox (QuickJS) in the Rust engine, so they behave the same in the app, Runner, CLI and MCP.

API

ObjectMembers
pm.environment, pm.globalsget, set, unset, has, toObject
pm.variablesget, set, has, replaceIn, toObject
pm.iterationDataget, has, toObject (Runner data rows)
pm.cookiesget, has, toObject, jar().clear(url)
pm.requesturl, method, body, headers.add/upsert/get/remove
pm.responsejson(), text(), code, responseTime, headers.get
pm.test(name, fn), pm.expect(value)chai-style matchers: equal, eql, ok, above, below, include, match, property, lengthOf, status and more
console.log, JSONOutput goes to the Console panel.

Examples

// Pre-request: add a header
pm.request.headers.add('X-Request-Id', pm.variables.get('requestId'));

// Tests: check and save a field for the next request
pm.test('created', () => pm.expect(pm.response).to.have.status(201));
pm.environment.set('paymentId', pm.response.json().id);

Start a run

Open Runner, pick a collection or folder (or right-click one in the tree and choose Run in Runner), and set up the run. You can select and drag to reorder requests, choose an environment and set the delay between requests. Pause, resume or stop a run in progress.

Data-driven runs

Attach a CSV or JSON file: each row is an iteration and each column is a variable, readable with {{column}} or pm.iterationData. A JSON file must be an array of objects. The row count sets the number of iterations.

Steps that ask for input

Right-click any {{variable}} in a request and choose Ask on send: an SMS code, an amount, a currency, a confirmation. Pick a type (text, number, code, secret, choice, yes/no, JSON, file), a label and checks. Send opens a small form by the button; the Runner stops at that step, shows the form in the run log and goes on after the answer. A 4xx on a step with typed input opens the form again (three tries). A file field goes as a path where a request takes a file and as base64 where it sits in a text body (up to 10 MB). Give a code a lifetime and the card counts it down; Resend runs the step before again (the one that sent the code) and asks once more. The value lives only in that run: it is not saved to environments, history or run records, and a code is shown as ••••13 in the log. The field definitions are stored in .bonk/inputs.json, so commit it. In the CLI nobody can type: pass the value with --input otp=123456 or BONK_INPUT_otp, or the step fails.

Run settings

  • Stop on first failure.
  • Save responses: for the report and for comparing runs.
  • A gRPC deadline for gRPC requests.

Results

Results show per-iteration status, timing, a waterfall and test details. Rerun only the failed requests, reopen past runs from history and export a JSON report.

Scenarios

Choose Save to workspace to store the setup in .bonk/scenarios.json: relative request paths, public variable defaults, iterations, delay and stop-on-failure. Secret values and secret-named data columns are omitted, only the required names are kept. Commit the file, then repeat the same run in the CLI or from MCP:

BONK_VAR_TOKEN="$TOKEN" bonk run --workspace ./api --scenario smoke

Install

Homebrew on macOS and Linux, or a single binary from GitHub Releases on any platform.

brew install nekidaz/tap/bonk

# or a release archive (bonk.exe on Windows)
curl -L https://github.com/nekidaz/.bonk/releases/latest/download/bonk-aarch64-apple-darwin.tar.gz | tar -xz

Run a collection

Point it at the whole workspace, a folder or a single request. Environments are the ones saved in the app.

# the whole workspace (run from its root)
bonk run

# a folder and one request, with an environment
bonk run api/users api/health.bonk.json --env Staging

# CI: stop at the first failure, write a JUnit report
BONK_VAR_TOKEN=$TOKEN bonk run api --bail --junit report.xml

Exit codes

CodeMeaning
0Every request passed
1Something failed: status, test or script
2The run couldn’t start: bad path, unknown environment, invalid data file

Secrets

Data, scenarios and network

  • --data users.csv runs one iteration per CSV or JSON row.
  • --var NAME=VALUE sets a variable. --json report.json writes a JSON report.
  • --workspace DIR --scenario NAME repeats a scenario saved in the workspace from any directory.
  • --app-state FILE reads the app's globals and environments from another state.json.
  • Proxy and TLS: --proxy, --no-proxy, --cacert, --cert / --key, --p12 and -k.

Run bonk run --help for every flag.

One-click setup

  1. Open the workspace the AI should use, then Settings → AI / MCP.
  2. Choose whether to allow workspace edits and API calls, an environment, and an optional host allowlist.
  3. Click Install for all clients and restart the configured apps.

bonk configures Claude Desktop, Claude Code and ChatGPT/Codex. Existing client settings are preserved, and a *.bonk-backup is made before the first change. Remove from clients removes only the bonk entry. The desktop app does not need to stay open.

What the agent can do

  • List, read, create, update, rename, move, duplicate and delete requests and folders.
  • Validate, send or run saved HTTP requests, with scripts and tests.
  • Reflect gRPC schemas, compile local .proto files, generate examples and make unary calls.
  • Run a saved scenario with run_scenario.
  • Steps that ask for input: list_inputs shows the fields, inputs carries values the user gave the agent, and a missing one is asked from the user through MCP elicitation (a confirmation always is).

Permissions

OptionEffect
--read-onlyDisable every filesystem mutation tool.
--no-networkDisable HTTP calls, gRPC calls and reflection.
--target-host HOSTOutbound host allowlist, repeatable, supports *.domain.
--mutating-methods allow|ask|denyPolicy for POST, PUT, PATCH and DELETE. ask is the default.
--environment NAMEApp environment the model may use, repeatable.

Secrets provided as BONK_VAR_TOKEN resolve {{TOKEN}} without being shown to the model. Stored credentials are redacted from results by default.

Manual and remote use

# STDIO, restricted
bonk-mcp --workspace /path/to/workspace --read-only --no-network

# Streamable HTTP on loopback, endpoint /mcp
BONK_MCP_TOKEN='long-random-token' \
bonk-mcp --workspace /path/to/workspace http --bind 127.0.0.1:8000

A non-loopback bind needs a token, at least one --mcp-host, and either --target-host or --allow-all-targets. Terminate TLS at a reverse proxy. Run bonk-mcp --help for every option.

Everyday work

Open the Source Control tab to see changed requests. Stage and commit, view diffs inline or side by side, stage or discard individual lines, and use stashes. Branches show ahead and behind counts, and Pull, Push and publish are available. Auto-fetch keeps the status current. Remotes are managed in settings.

History and graph

A commit graph supports cherry-pick, revert, reset, tags, compare and Undo. You can also see the Git history of a single request, use interactive rebase and the reflog, and clone a repository.

Conflicts

Conflicts open in a three-way merge that can merge a request field by field.

Import

One import window handles everything. Bring a source from a file, a link, a paste or a drop, and the format is detected from the content.

FormatNotes
OpenAPI 3.x, Swagger 2.0Group by tags, paths or flat. Servers become environments, body examples come from the schema.
Postman v2.1Collections and variables.
Insomnia v4Export files.
HARChoose which request types to take.
cURLOne or more commands, also pasteable into the URL bar.

A preview with warnings comes before anything is written. Re-importing a source offers update from spec, which updates the collection and keeps your edits. For gRPC, load .proto files in the gRPC editor.

Export

In Settings → Data and import, export the workspace as Bonk JSON or Postman Collection v2.1. Keychain secret values are not exported unless you turn on Include secrets.

The CLI can import a version-1 Bonk JSON export:

bonk import export.json --workspace ./api

Code snippets

Any request can be copied as cURL or generated as code. See HTTP.

Request

ActionmacOSWindows/Linux
Send request⌘↵Ctrl+Enter
Save⌘SCtrl+S
Save As⇧⌘SCtrl+Shift+S
Request code⌥⌘ECtrl+Alt+E
New request⌘NCtrl+N
New gRPC request⌥⌘NCtrl+Alt+N
New collection⇧⌘NCtrl+Shift+N
New folder⇧⌘FCtrl+Shift+F
Expand editor or response⌥⌘FCtrl+Alt+F
Show / collapse response⇧⌘RCtrl+Shift+R
Show / collapse request body⇧⌘ECtrl+Shift+E
ActionmacOSWindows/Linux
Command palette⌘KCtrl+K
Environment⌘ECtrl+E
Show / hide sidebar⌘\ or ⌘BCtrl+\ or Ctrl+B
Collections⌘1Ctrl+1
History⌘2Ctrl+2
Bottom panel⌘JCtrl+J
Terminal⌃`Ctrl+`
Issues⇧⌘MCtrl+Shift+M
Issues full height⇧⌘JCtrl+Shift+J
Switch workspace⇧⌘OCtrl+Shift+O
Open workspace folder⌘OCtrl+O
Settings⌘,Ctrl+,

Tabs

ActionmacOSWindows/Linux
New tab⌘TCtrl+T
Close tab⌘WCtrl+W
Close all tabs⌥⌘WCtrl+Alt+W
Reopen closed tab⇧⌘TCtrl+Shift+T
Next tab⌃TabCtrl+Tab
Previous tab⌃⇧TabCtrl+Shift+Tab

Pages

PageWhat it controls
GeneralInterface language (English or Russian), what opens on startup (empty window or last tabs), tab behavior, confirm closing unsaved tabs, check for updates.
RequestsRequest timeout, follow redirects, verify SSL certificates, format JSON, response preview size, wrap long lines.
VariablesDynamic variable language, one value per request, keep values, seed.
CookiesThe cookie jar.
ProxySystem, manual or no proxy, with address, login and exceptions.
CertificatesTrusted CAs, trust system CAs, client certificates per host (mTLS).
gRPCReflection, .proto import paths, default deadline, max message size, default fields.
AI / MCPClient install, permissions, environments, allowed hosts and the call log. See MCP.
AppearanceTheme, text size, density, shape and fonts, request/response layout.
HotkeysRebind any shortcut. Conflicts are highlighted.
Data and importImport, export, history retention and the data folder.

Themes

Bonk Dark, Bonk Light, Gruvbox Dark, Catppuccin Mocha, Nord and Solarized Light ship with the app. You can follow the system appearance, pick a theme with ⌘K, and import Zed or VS Code themes.

Where data lives

Requests are in the workspace folder. Preferences, history and session state are in the platform application-data directory, shown under Data and import. Secret variables use the OS keychain.

0.2.0

Released 2026-10-11.

  • Git: a Source Control tab with staging, diffs, branches, a commit graph and three-way merge.
  • OAuth 2.0 auth: authorization code with PKCE, client credentials and password.
  • A Scripts tab with a results panel, dynamic variables, and a per-workspace cookie jar.
  • The bonk CLI with JUnit and JSON reports, and portable workspace scenarios.
  • New themes, a Console, terminal and Issues panel, and one import window with preview.
  • HTTP Send and unary gRPC use the same execution pipeline as collections, CLI and MCP. The Flows canvas was removed.

0.1.9

Released 2026-10-10.

  • The window adapts down to 720×520, and large workspaces open with folders collapsed.
  • {{vars}} resolve before auth, and MCP sends HTTP requests like the app does.

0.1.8

Released 2026-10-09.

  • Drag and drop in the sidebar tree, a large-response viewer, Save As, and PKCS#12 client certificates.
  • Runner presets, Postman export, and folder-level auth.

Full history: CHANGELOG.md on GitHub.