Mándalo

Home/Docs/Getting started

Getting started

Install the app, point it at a directory, and send a request. It takes about a minute, and nothing you do here leaves your machine.

Desktop or browser

Mándalo runs two ways from the same code. The desktop app is a Tauri shell around the Rust core; the web app runs the same client entirely in your browser. Neither one has a server behind it — the browser build is not a hosted service, it is the client running on your machine.

The browser build stores collections in the browser, and on Chromium it can open a real local folder through the File System Access API, so your collections stay actual .http files in your git checkout. One genuine difference is worth knowing before you start:

CORS in the browser build

A page in a browser can only call hosts that send CORS headers, and can only read response headers the server marks with Access-Control-Expose-Headers (beyond the safelisted ones). That is a browser rule, not a Mándalo rule, and it applies to every browser-based client. The desktop app talks to the network from Rust and has no such restriction, so it is the right choice for APIs you do not control.

Install the desktop app

Builds for macOS, Windows and Linux are attached to every release on GitHub. Grab the one for your platform from the latest release page:

  • macOS — open the disk image and drag Mándalo into /Applications.
  • Windows — run the installer.
  • Linux — take the AppImage or the .deb, whichever suits your distribution.

On macOS the disk image comes in three flavours — Apple silicon, Intel, and a universal build that runs on both. Take the universal one if you are not sure.

The builds are not code-signed by a paid certificate, so macOS Gatekeeper and Windows SmartScreen will ask you to confirm the first launch. If you would rather not trust a binary, the project is open source — pnpm install && pnpm tauri dev builds it from source.

Or the command line, or your editor

The desktop app is one of three ways in, and they read the same workspace directory.

  • Command line — curl -fsSL https://mandalo.dev/install.sh | sh on macOS or Linux, or brew install De-Rus/tap/mandalo. It verifies the download against the release checksums and installs into ~/.local/bin without sudo. See CLI & CI.
  • VS Code or Cursor — download the .vsix for your platform from the release page and run code --install-extension mandalo-<platform>-<version>.vsix. The per-platform builds bundle the CLI, so gRPC works immediately; the universal build does not, and needs mandalo on your PATH for gRPC. It is not on the Marketplace yet.
  • Browser — mandalo.dev/app, nothing to install at all.

Pick a workspace directory

A workspace is just a directory on disk. Everything you create in the app is written there as text. The default is ~/Mandalo; point it at a checkout of your API repo instead and your collections become part of that repo.

On first open, Mándalo creates the skeleton:

my-workspace/
  mandalo.toml          # workspace manifest: schema version, id, name
  environments/         # one TOML file per environment
  collections/          # one directory per collection

You can register several workspaces and switch between them — one per repository is a good default. The registry of known workspaces lives in your OS config directory, not in the workspace itself, so it never pollutes a repo.

Create a collection

Create a collection from the sidebar and give it a name. Mándalo slugifies the name into a directory and writes a manifest:

collections/payments-api/
  collection.toml       # schema_version, id, name
  list-charges.http     # one file per request
  users/                # folders are directories
    create.http

Folders are real directories and requests are real files, so moving a request between folders is a file move and shows up in git as one. The full layout is in Collections & git.

Your first request

Pick a method, type a URL, hit Send. For a request you want to keep, save it into a collection — that write lands on disk immediately.

The request editor covers the three kinds Mándalo speaks:

  • HTTP — method, URL, headers, body.
  • GraphQL — a query and a JSON variables document; Mándalo posts them as {"query": …, "variables": …}. Invalid variables JSON is an error, not a silently empty object.
  • gRPC — proto file paths, a service and method, and a JSON message. See gRPC.

Auth is a field on the request, not a header you hand-roll: none, bearer, basic, or apikey with the key placed in a header or in the query string.

Add an environment

Hard-coded hostnames age badly. Create an environment — staging, say — with a baseUrl variable, and write your URL as {{baseUrl}}/v1/charges. Each environment is one file:

# environments/staging.toml
name = "staging"

[vars]
baseUrl = "https://api.staging.example.com"
apiVersion = "2026-08-01"

Interpolation applies to the URL, headers, body, auth fields, GraphQL query and variables, and gRPC message and metadata. A variable that no environment resolves is a hard error — Mándalo will not send a request with a literal {{baseUrl}} in it. Details in Environments & variables.

Send and read the response

Send gives you the status line, the elapsed time, the response size, and tabs for the body and the headers. JSON bodies are pretty-printed and highlighted.

One thing worth internalising: a non-2xx response is a result, not an error. A 404 renders like any other response, with its body and headers intact, because that is frequently the thing you were testing. Only transport-level failures — DNS, TLS, connection refused, timeouts — surface as errors.

Next