Hoppscotch User Guide

1. Quick Start

Hoppscotch is an open-source API development ecosystem that lets you design, test, and debug HTTP, GraphQL, WebSocket, SSE, MQTT, and Socket.IO APIs from a web browser, desktop application, or command line. It supports team collaboration with shared collections, environments, and workspaces.

Key features:

• Multi-protocol support: REST, GraphQL, WebSocket, SSE, MQTT, Socket.IO (v2/v3/v4)
• Team workspaces with shared collections and environments
• Pre-request scripts and test scripts with a JavaScript sandbox
• Import/export from Postman, Insomnia, OpenAPI, cURL, and HAR
• Environment variables with secret masking
• Code generation for multiple languages
• Desktop app with native request handling (TLS certificates, proxies, NTLM)
• CLI for CI/CD pipeline integration
• Self-hosted deployment option with admin dashboard

Prerequisites: A modern web browser, or Node.js >= 22 for the CLI.

Quickest path — use the hosted version:

Open hoppscotch.io in your browser and start making requests immediately. No install required.

Quickest path — CLI:

npm install -g @hoppscotch/cli
hopp test -e environment.json collection.json

Test Results:
  Total: 5
  Passed: 5
  Failed: 0
  Duration: 1.2s

What to try next: See Installation for all deployment options, Configuration for environment setup, or Core Usage for protocol-specific guides.

2. Installation

System Requirements

Web (Hosted)

No installation needed. Navigate to hoppscotch.io and sign in with Google, GitHub, Microsoft, or email.

Tip

The hosted version at hoppscotch.io is always up to date. Use this if you do not need self-hosting or offline access.

CLI Installation

The CLI package is published as @hoppscotch/cli with the binary name hopp.

npm

npm install -g @hoppscotch/cli

pnpm

pnpm add -g @hoppscotch/cli

npx (no install)

npx @hoppscotch/cli test collection.json

Verify installation:

hopp --version

0.30.3

Important

The CLI requires Node.js >= 22. Earlier versions will fail with a compatibility error. The isolated-vm native dependency requires a C++ build toolchain (Python 3 + build-essential on Linux, Xcode CLI tools on macOS, or Visual Studio Build Tools on Windows).

Desktop Application

Download the desktop app from the Hoppscotch releases page. The desktop app is built with Tauri 2 and provides native HTTP handling via libcurl, including client certificate support, proxy authentication, and NTLM.

The desktop app supports two modes:

• Standard mode (default): stores configuration in the OS-specific config directory
• Portable mode: stores all data alongside the executable, suitable for USB drives

Note

The desktop app auto-updates by default. You can check for updates manually or disable auto-update in settings. Portable mode does not support auto-updates.

Hoppscotch Agent

The Hoppscotch Agent is a lightweight companion app that runs locally and proxies HTTP requests from the web app through your machine. This enables access to localhost services, private networks, and client certificates without installing the full desktop app.

1. Download the Agent from the releases page
2. Launch the Agent — it starts in the system tray
3. In the Hoppscotch web app, select Agent as your request interceptor
4. Complete the OTP registration when prompted

The Agent uses X25519 key exchange with AES-GCM encryption for secure communication between the browser and local agent.

Self-Hosted Deployment

For self-hosting instructions including Docker Compose setup, PostgreSQL configuration, and environment variables, see the Admin Guide.

Install Troubleshooting

Error: isolated-vm build fails during CLI install

Cause: Missing C++ build toolchain required by the isolated-vm native module.

Solution:

Linux

sudo apt install build-essential python3
npm install -g @hoppscotch/cli

macOS

xcode-select --install
npm install -g @hoppscotch/cli

Windows

npm install -g windows-build-tools
npm install -g @hoppscotch/cli

Prevention: Ensure build tools are installed before installing the CLI.

Error: EACCES permission denied during global install

Cause: npm global directory requires elevated permissions.

Solution:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @hoppscotch/cli

Prevention: Configure npm to use a user-writable global directory.

Error: Node.js version incompatible

Cause: CLI requires Node.js >= 22.

Solution:

nvm install 22
nvm use 22
npm install -g @hoppscotch/cli

Desktop app appears unresponsive after launch with large collections

Cause: Loading very large collections at startup can block the UI thread temporarily. (Community issue #5694)

Solution: Wait for the initial load to complete. If the app remains unresponsive for more than 30 seconds, try clearing the local cache by deleting the app's config directory and restarting.

Agent registration fails with OTP timeout

Cause: The OTP window has a limited validity period.

Solution: Ensure both the web app and the Agent are on the same network. Restart the Agent and try the registration again promptly.

3. Configuration

Environments

Hoppscotch uses environments to manage variables across requests. Variables are referenced with double curly braces: {{variable_name}}.

To create an environment:

1. Click Environments in the sidebar
2. Click New Environment
3. Add key-value pairs
4. Toggle Secret for sensitive values (passwords, tokens)

Tip

Secret environment variables are masked in the UI and never synced to the server in plaintext. Use them for API keys, passwords, and tokens.

Request Interceptors

Interceptors determine how HTTP requests are sent from the app:

Select your interceptor in Settings > Interceptor.

Warning

The Browser interceptor is subject to browser CORS restrictions. If you receive CORS errors, switch to the Agent, Extension, or Proxy interceptor.

User Settings

Available settings in Settings:

• Theme: System, Light, Dark
• Language: 20+ languages via i18n
• Font size: Adjustable editor font size
• Interceptor: Browser, Proxy, Agent, Extension, Native
• Proxy URL: Custom proxy endpoint (when using Proxy interceptor)
• Extensions: Enable/disable experimental features

For the full configuration reference (backend environment variables, Docker settings, admin configuration), see the Admin Guide.

4. Core Usage

Making REST Requests

1. Select the HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE, CUSTOM)
2. Enter the request URL — environment variables are expanded automatically
3. Configure headers, query parameters, body, and authorization
4. Click Send

The response panel shows:

• Status code and timing
• Response headers
• Response body with syntax highlighting (JSON, XML, HTML, raw)
• Response size

Body types:

Authorization types:

Note

NTLM and Digest authentication require the Desktop app or Agent interceptor since they depend on the native libcurl relay engine.

Making GraphQL Requests

1. Switch to the GraphQL tab
2. Enter the GraphQL endpoint URL
3. Write your query in the editor — schema auto-completion is available once the schema is fetched
4. Add variables in the Variables panel (JSON format)
5. Set headers (e.g., Authorization) as needed
6. Click Send

The editor uses a custom CodeMirror extension (@hoppscotch/codemirror-lang-graphql) for GraphQL syntax highlighting, auto-completion, and error linting.

Tip

Click the Schema button to fetch and browse the introspected schema. This powers auto-completion and validation in the query editor.

Realtime Protocols

Hoppscotch supports testing realtime APIs:

WebSocket:

1. Navigate to Realtime > WebSocket
2. Enter the WebSocket URL (ws:// or wss://)
3. Click Connect
4. Send and receive messages in real time

Server-Sent Events (SSE):

1. Navigate to Realtime > SSE
2. Enter the SSE endpoint URL
3. Click Connect to start listening

MQTT:

1. Navigate to Realtime > MQTT
2. Enter the broker URL
3. Subscribe to topics and publish messages

Socket.IO:

1. Navigate to Realtime > Socket.IO
2. Enter the server URL
3. Select the Socket.IO version (v2, v3, or v4)
4. Connect and emit/listen to events

Important

Socket.IO version must match the server version exactly. Using v4 client against a v2 server (or vice versa) will fail silently. Check your server's Socket.IO dependency version.

Collections

Collections organize your requests into folders for reuse and sharing.

Creating a collection:

1. Click Collections in the sidebar
2. Click New Collection
3. Name your collection and optionally set collection-level headers and authorization

Organizing requests:

• Drag and drop requests between folders
• Nest folders up to arbitrary depth
• Set collection-level auth and headers that propagate to all child requests

Sharing collections:

• In personal workspace: collections are private to your account
• In team workspace: collections are shared with all team members based on role (Owner, Editor, Viewer)

Team Workspaces

Team workspaces enable collaboration:

1. Create a team in Settings > Teams
2. Invite members by email
3. Assign roles: Owner, Editor, or Viewer
4. Switch to the team workspace to access shared collections and environments

Pre-Request and Test Scripts

Hoppscotch supports JavaScript scripts that run before requests (pre-request) and after responses (test scripts). Scripts execute in a sandboxed environment (@hoppscotch/js-sandbox) using either the faraday-cage WebAssembly sandbox (default) or isolated-vm (Node.js/CLI).

Pre-request script example:

pw.env.set("timestamp", Date.now().toString())
pw.env.set("authToken", "Bearer " + pw.env.get("token"))

Test script example:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200)
})

pw.test("Response has data", () => {
  const body = pw.response.body
  pw.expect(body.data).toBeType("object")
})

Available script APIs:

Warning

The --legacy-sandbox CLI flag opts out of the new faraday-cage sandbox and uses isolated-vm instead. The legacy sandbox may be removed in a future release.

Mock Server

Create mock API endpoints for testing:

1. Navigate to the Mock Server section
2. Define mock routes with response status, headers, and body
3. Share mock server URLs with your team

5. Common Tasks

Import a Postman Collection

1. Click Import/Export in the sidebar
2. Select Import
3. Choose Postman as the source format
4. Upload your Postman Collection JSON file (v2.0 or v2.1)
5. The collection, including folders, requests, and variables, will appear in your workspace

Note

Some Postman-specific features (monitors, mock servers, Postman-specific dynamic variables) are not imported. If you encounter TypeError: e.replaceAll is not a function during import, ensure your collection file is a valid Postman v2.x JSON export. (Community issue #5755)

Import from OpenAPI/Swagger

1. Click Import/Export > Import
2. Select OpenAPI as the source format
3. Provide the OpenAPI specification (JSON/YAML, v2.0 or v3.x) as a file or URL
4. Hoppscotch generates requests for each endpoint defined in the spec

Import from cURL

1. Click Import/Export > Import
2. Select cURL
3. Paste your cURL command
4. The request method, URL, headers, and body are populated automatically

Export a Collection

1. Right-click a collection in the sidebar
2. Select Export
3. Choose the format: Hoppscotch JSON or OpenAPI
4. Save the file

Generate Code Snippets

1. After configuring a request, click the Code button (</> icon)
2. Select the target language and library (JavaScript/fetch, Python/requests, cURL, Go, etc.)
3. Copy the generated code to your clipboard

Run Tests in CI/CD with the CLI

hopp test \
  --env environment.json \
  --delay 500 \
  collection.json

Running tests...

  Collection: My API Tests
    Folder: User Endpoints
      GET /users
        ✓ Status is 200
        ✓ Response has users array
      POST /users
        ✓ Status is 201
        ✓ User was created

Test Results:
  Total: 4  Passed: 4  Failed: 0
  Duration: 2.3s

CLI options for the test command:

Share a Request via Shortcode

1. Configure your request
2. Click Share
3. A unique short URL is generated
4. Recipients can open the URL to load the exact request configuration

Use the Spotlight Search

Press Ctrl+K (or Cmd+K on macOS) to open the spotlight search. Search across:

• Request history
• Collections and requests
• Environments
• Navigation (switch tabs, open settings)

Set Up OAuth 2.0 Authentication

1. In the request's Authorization tab, select OAuth 2.0
2. Choose the grant type:
   • Authorization Code — redirects to the provider for user consent
   • Client Credentials — server-to-server auth
   • Password — resource owner password credentials
   • Implicit — browser-only flow (deprecated, avoid for new integrations)
3. Fill in the token endpoint, client ID, client secret, and scopes
4. Click Get Token to obtain an access token
5. The token is automatically applied to the request

Published API Documentation

Teams can publish API documentation from collections:

1. In a team workspace, right-click a collection
2. Select Publish Documentation
3. Share the generated documentation URL with consumers
4. Documentation includes request details, example bodies, and environment references

6. Troubleshooting

Diagnostic Decision Tree

Request fails
├── CORS error in response?
│   ├── Yes → Switch interceptor to Agent, Extension, or Proxy
│   └── No ↓
├── Connection refused / timeout?
│   ├── Target is localhost? → Use Agent or Desktop app
│   ├── Network reachable? → Check firewall/VPN
│   └── TLS error? → Use Desktop/Agent for custom certificates
├── Authentication error?
│   ├── 401 → Check token expiry, verify Authorization header
│   └── 403 → Check permissions/scopes
├── Script error?
│   ├── Pre-request → Check variable references in pw.env
│   └── Test script → Verify pw.response.body parsing
└── Import error?
    ├── Postman → Ensure v2.0/v2.1 JSON format
    └── OpenAPI → Validate spec with editor.swagger.io

Error: CORS policy blocks request

Cause: The browser interceptor cannot bypass CORS restrictions set by the target server.

Solution:

1. Switch to the Agent interceptor (install the Hoppscotch Agent first)
2. Or switch to the Proxy interceptor and configure a proxy URL
3. Or install the Hoppscotch browser extension and use the Extension interceptor

Prevention: Use the Agent or Desktop app for APIs that don't set permissive CORS headers.

Error: REQUEST_ERROR in CLI test output

Cause: Network connectivity issue between the CLI and the target server.

Solution:

1. Verify the target URL is reachable: curl -I <url>
2. Check that environment variables resolve correctly: hopp test --env env.json --dry-run collection.json
3. If targeting httpbin.org or other external services, transient failures are possible — retry

Prevention: Use local mock servers for CI/CD pipelines to avoid external service dependencies.

Error: Users keep signing out after 24 hours (self-hosted)

Cause: JWT refresh token configuration or cookie settings mismatch. (Community issue #5121)

Solution:

1. Verify REFRESH_TOKEN_VALIDITY in your backend .env file
2. Ensure cookies are set with SameSite=Lax and Secure flags match your deployment (HTTPS vs HTTP)
3. Check that your reverse proxy is forwarding cookies correctly

Prevention: Set REFRESH_TOKEN_VALIDITY to an appropriate duration (e.g., 604800000 for 7 days).

Error: Importing collections reports TypeError: e.replaceAll is not a function

Cause: Invalid Postman collection format or Node.js version too old. (Community issue #5755)

Solution:

1. Ensure the imported file is a valid Postman Collection v2.0 or v2.1 JSON
2. Re-export from Postman using Export > Collection v2.1
3. If using the CLI, ensure Node.js >= 22

Error: Header array values cause errors

Cause: Headers with array values instead of string values can cause request failures. (Community issue #6132)

Solution: Ensure all header values are strings. If you need multiple values for a header, join them with commas per HTTP specification.

Error: Empty SMTP credentials rejected in self-hosted setup

Cause: The backend validates MAILER_SMTP_USER and MAILER_SMTP_PASSWORD and rejects empty strings as invalid. (Community issue #4586)

Solution: If your SMTP server doesn't require authentication, set these to placeholder values or configure a mailer that doesn't require credentials.

Error: Cookie values truncated when tokens contain = characters

Cause: Cookie parsing splits on = and discards subsequent segments. (Community issue #6135)

Solution: URL-encode cookie values that contain = characters before setting them.

Error: Personal workspace data loss when switching between desktop and browser

Cause: Race condition in local state sync when the same account is used simultaneously in desktop and browser clients. (Community issue #6138)

Solution: Avoid using both clients simultaneously with the same personal workspace. Use team workspaces for multi-device access — they sync through the backend and avoid local state conflicts.

Caution

Do not open the same personal workspace in both the desktop app and web browser simultaneously. This can cause data duplication or loss due to local state sync conflicts.

Desktop: App unresponsive on launch

Cause: Large collections being loaded at startup can block the UI thread. (Community issue #5694)

Solution:

1. Wait up to 30 seconds for the initial load
2. If persistent, delete the config directory to reset local state:
   • Windows: %APPDATA%\hoppscotch-desktop
   • macOS: ~/Library/Application Support/hoppscotch-desktop
   • Linux: ~/.config/hoppscotch-desktop

CLI: Test script reports hasFailedTestCases incorrectly

Cause: A fixed bug where the CLI incorrectly reported test pass/fail status. (Community issue #6118)

Solution: Update to the latest CLI version: npm install -g @hoppscotch/cli@latest

Warning

When running CLI tests against external services (e.g., httpbin.org), transient network errors (ECONNRESET, DNS timeouts) can cause false failures. The CLI automatically retries once for known transient errors. For CI stability, prefer local mock servers.

7. FAQ

Q: What is the difference between the web app, desktop app, and CLI?

The web app runs in your browser and is the primary interface for interactive API testing. The desktop app provides the same interface with native HTTP handling (TLS certificates, proxies, NTLM, localhost access without an agent). The CLI (hopp) runs collections and test scripts headlessly for CI/CD integration.

Q: How do I access localhost APIs from the web app?

Use either the Hoppscotch Agent or the Desktop app. The browser's security model prevents the web app from directly accessing localhost. The Agent runs locally and proxies requests through your machine.

Q: What import formats are supported?

Hoppscotch imports from: Postman (v2.0/v2.1), Insomnia, OpenAPI/Swagger (v2.0/v3.x), cURL commands, HAR files, and Hoppscotch's own JSON format.

Q: Can I use Hoppscotch offline?

The desktop app works fully offline for requests to reachable servers. The web app requires an initial load but can work with a service worker for cached resources. The CLI works fully offline (no authentication needed for local collections).

Q: How do I authenticate the CLI with a self-hosted instance?

Use the --server and --token flags:

hopp test --server https://your-instance.com --token <personal-access-token> collection.json

Personal access tokens can be generated in your self-hosted Hoppscotch account settings.

Q: What realtime protocols does Hoppscotch support?

WebSocket, Server-Sent Events (SSE), MQTT, and Socket.IO (versions 2, 3, and 4).

Q: How does the scripting sandbox work?

Scripts run in an isolated sandbox — faraday-cage (WebAssembly) in the web/desktop app, or isolated-vm (V8 isolate) in the CLI. Scripts cannot access the filesystem, network, or DOM. They interact with requests and responses through the pw API namespace.

Q: Can I customize the request timeout?

In the web app, timeouts are controlled by the interceptor. The Agent and Desktop native interceptor support configurable timeouts. In the CLI, timeouts are controlled by the underlying HTTP client (axios).

Q: How do I set custom fonts or font sizes?

Custom font family is not currently configurable in the desktop app (Community issue #3536). Font size for the code editor can be adjusted in Settings.

Q: How are team environments different from personal environments?

Personal environments are scoped to your account and synced only to your devices. Team environments are shared with all team members and synced through the backend. Secret values in team environments are encrypted and only decrypted client-side.

Q: What is the Hoppscotch proxy?

The proxy (proxy.hoppscotch.io for the hosted version) is a server-side intermediary that forwards requests from the web app to bypass CORS restrictions. Self-hosted deployments can configure their own proxy URL. (Community issue #6103)