Skip to main content
hitspec Studio is the desktop companion to hitspec studio: the same keyboard-friendly workflow in a native window instead of a terminal. It edits and runs the exact same plain-text .http files, so what you click in the app is what CI executes.
The desktop app is developed in this repository under apps/desktop. There are no published installers yet: signed and notarized builds need Apple and Windows signing credentials that are not set up, so nothing is attached to the GitHub releases. Today you run it from source (below) or package an unsigned build yourself (Package it). It also needs hitspec v2.20.0 or newer: the app warns when the CLI it launches is older.

Run it from source

1

Install dependencies

2

Build the CLI it drives

3

Launch

Open a workspace with cmd/ctrl+O, by dropping a folder on the app icon, or by passing a directory on the command line. Recent workspaces are remembered on the welcome screen.

What you get

  • Workspace browser — file tree with request counts, fuzzy filter, and a per-file request list with pass/fail dots from the last run.
  • Request inspector — method, URL, headers, query params, body, assertions, captures and metadata (@timeout, @depends, @auth, …).
  • Runner — run one request (cmd/ctrl+enter) or the whole file (cmd/ctrl+shift+enter) with live per-request progress, then a tabbed response viewer: pretty-printed JSON body, headers, assertion results, timing, captures and SSE events.
  • Source editor — line numbers plus .http syntax highlighting, save (cmd/ctrl+s), revert, and automatic reload when the file changes on disk.
  • Environments — switch from the toolbar or edit variables in a grid that writes straight back to hitspec.yaml.
  • History — the persistent SQLite run history with per-run drill-down.
  • Stress, mock, record — the same engines as the CLI, with live metrics charts, route tables and recording export to .http.
  • Import — curl, OpenAPI and Insomnia sources previewed as .http before you save them into the workspace.
  • Command palette (cmd/ctrl+k) and five themes shared with the terminal UI.

How it works

The app spawns hitspec serve --api-only as a child process on a random loopback port with a freshly generated bearer token (handed over through the child’s environment, never its command line), then drives the REST and WebSocket API from packages/serve. The renderer never talks to the network and never sees the token: every call crosses a small IPC bridge in the main process, and file writes outside the workspace are only allowed for paths you picked in a native save dialog.
Because it reuses the API server, every capability added to packages/serve becomes available to the desktop app without new native code.

Safety rails

  • The renderer is treated as untrusted: only the app’s own page can call the main process, and REST calls are limited to the endpoints the UI uses.
  • Shell execution (--allow-shell) can only be switched on through a native confirmation dialog for the current workspace, and the approval lasts until you quit the app.
  • Unsaved editor changes are guarded when you switch files, close the window, quit or open another workspace, and saving asks before overwriting a file that changed on disk since you opened it.
  • The API server is started with --parent-pid, so it shuts itself down within a second when the app dies without cleaning up (a crash or kill -9). A hitspec CLI older than that flag is started without it; the next launch then stops the leftover server instead, after checking its command line and port so an unrelated process that reused the pid is never touched.
  • Launching the app again with a folder (hitspec-studio ./other-project, or “Open With” in Finder) opens that folder in the running window, asking first if there are unsaved edits.
  • “Read-only” in Settings protects the workspace and hitspec.yaml: saving, creating or deleting files and editing settings are refused, while running requests, stress, mock and history reads keep working.

Package it

task desktop:dist packages for the operating system you run it on (mac: arm64 and x64, Windows: x64, Linux: x64). It first cross-compiles one CLI per architecture into apps/desktop/build/bin/<os>-<arch>/ and bundles the one that matches each target, so the Intel build never carries the Apple-silicon binary. Installers land in apps/desktop/release/. Local builds are unsigned unless your machine has a signing certificate (CSC_LINK, or a “Developer ID Application” certificate in your keychain); set CSC_IDENTITY_AUTO_DISCOVERY=false to force an unsigned build. Clear the quarantine flag after installing an unsigned build on macOS:
CI (.github/workflows/desktop.yml) packages all three platforms on every change to the app and verifies the bundled CLI and the hardened Electron fuses. Signed installers and release publishing run only when the signing credentials exist in the repository secrets; until then they are skipped.

Testing

The e2e suite launches the real app with Playwright against a throwaway workspace and an in-process HTTP target, so the whole stack — window, IPC, Go server, runner — is exercised on every run.
Last modified on October 19, 2026