Hoppscotch

Overview

Hoppscotch is an open-source API development tool and a lighter alternative to Postman. It sends REST, GraphQL, WebSocket, Server-Sent Events, Socket.IO and MQTT requests, with collections, environments, pre-request scripts, tests and code-snippet generation. It runs as a web app at hoppscotch.io (no account needed for quick requests), as a desktop app, or as a self-hosted instance (Community Edition is MIT licensed; Enterprise adds SSO, SCIM and audit features). Releases are date-versioned; the latest checked is 2026.9.0, and the @hoppscotch/cli package is 0.31.x and still labelled alpha.

Instructions

Step 1: Send a request and keep it

In the app choose a method, enter the URL, add headers, params, auth or a body, and press Send. Save the request into a collection. Use environments for values that change between servers: a variable baseUrl is referenced in URLs, headers and bodies as <<baseUrl>>. Browser requests are subject to CORS, so on the web app switch the interceptor to the Hoppscotch Agent (or use the desktop app, which has a native interceptor).

Import from Postman, Insomnia, OpenAPI or HAR through the Importer. Imported Postman scripts are converted only after you consent, and some pm.* features (for example pm.collectionVariables) are not supported.

Step 2: Scripts

Pre-request scripts and test scripts are JavaScript. The hopp namespace is the current API (experimental sandbox, on by default); the older pw namespace still works for existing scripts, and the docs advise against bulk-migrating them yet.

// Pre-request: fetch a token once, then attach it to this request
if (!hopp.env.get("accessToken")) {
  const res = await fetch(hopp.env.get("baseUrl") + "/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: hopp.env.get("clientId"),
      client_secret: hopp.env.get("clientSecret"),
    }),
  });
  hopp.env.set("accessToken", (await res.json()).access_token);
}
hopp.request.setHeader("Authorization", "Bearer " + hopp.env.get("accessToken"));

// Test script
hopp.test("order is created", () => {
  hopp.expect(hopp.response.statusCode).toBe(201);
  const order = hopp.response.body.asJSON();
  hopp.expect(order.items).toHaveLength(2);
});

Other helpers: hopp.env.set/get/delete/reset, hopp.env.global.*, hopp.request.setUrl/setMethod/setParam/setBody, hopp.response.headers/responseTime, hopp.cookies.*. The legacy equivalents are pw.env.get/set/unset, pw.response.status, pw.test, pw.expect. There is no pw.api helper; use fetch for extra HTTP calls (prefer the Agent or Native interceptor in the app).

Step 3: Run collections from the CLI

npm install -g @hoppscotch/cli       # requires Node.js 22+; build tools (python3, make, g++) on Linux
hopp --version

# a collection file exported from the app, with an exported environment file
hopp test -e staging.json orders-api.json
hopp test -e staging.json -d 500 orders-api.json --reporter-junit reports/orders-junit.xml

# several rounds with CSV data (header row = variable names)
hopp test orders-api.json --iteration-count 3 --iteration-data customers.csv

# a collection stored in a team workspace (personal workspace collections cannot be run this way)
hopp test clxsntdgh0000lcx9fnits2h8 --token "$HOPP_TOKEN" --server https://hoppscotch.brewline.dev

-e accepts an environment file or, with a token, an environment id. Create the personal access token in the app under settings; keep it in a CI secret. Exit code is non-zero if any test fails, so the command works as a CI gate. GraphQL requests in a collection run as HTTP POSTs; subscriptions cannot run in the CLI and are reported as errors.

Step 4: Self-host

Community Edition needs PostgreSQL and a .env file (values unquoted) with at least DATABASE_URL, a 32-character DATA_ENCRYPTION_KEY, WHITELISTED_ORIGINS, the VITE_BASE_URL / VITE_ADMIN_URL URLs and the three VITE_BACKEND_* URLs, plus an auth provider (see the Community Edition prerequisites page). The all-in-one image runs the app on 3000, admin dashboard on 3100 and backend on 3170:

docker pull hoppscotch/hoppscotch
docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch

Before the first start the database needs its tables: open a shell in the image (docker run -it --entrypoint sh --env-file .env hoppscotch/hoppscotch) and run pnpm exec prisma migrate deploy. Then open the admin dashboard on port 3100 to create the admin account. Individual images hoppscotch/hoppscotch-frontend, -backend and -admin exist for split deployments; a Helm chart covers Kubernetes. For the desktop app, enable subpath access (ENABLE_SUBPATH_BASED_ACCESS=true) and expose port 3200 of the frontend.

Step 5: Let an agent drive it (optional)

Hoppscotch ships an MCP server that exposes collections, environments and request execution to an agent. Register it with claude mcp add -s user hoppscotch -- npx -y @hoppscotch/mcp-server (Node.js 22+; sign in with a Cloud or self-hosted account).

Examples

Example 1: "Smoke-test the orders API in CI before every deploy"

Export the collection orders-api.json and the staging environment from the app, commit both, and add a CI step:

npm install -g @hoppscotch/cli
hopp test -e environments/staging.json orders-api.json --reporter-junit reports/orders-junit.xml

Result: each request prints its status and time, each hopp.test prints a check mark or a failure, and the job fails on the first broken assertion. Verified on a minimal collection against https://echo.hoppscotch.io: output ends with Test Cases: 0 failed 2 passed and a JUnit file is written.

Example 2: "Run Hoppscotch for our team on our own server"

Provision PostgreSQL, write .env with the URLs of your host, start the AIO container with the command above, run pnpm exec prisma migrate deploy, and open port 3100 to sign in as admin. Invite teammates there; shared workspaces then hold collections and environments for everyone, and CI jobs use --server and a personal access token.

Guidelines

• Keep secrets (clientSecret, tokens) in secret environment variables, not in exported collection files that go to Git.
• The CLI is alpha and requires Node.js 22 or newer; pin the version in CI and read release notes before upgrading (it follows 0.x versioning, so a minor bump can break).
• Test scripts decide what counts as failure: a 404 is a valid response to the CLI, so assert on hopp.response.statusCode.
• Browser CORS errors are an interceptor problem, not an API bug; switch to the Agent or desktop app.
• Self-hosted instances send anonymous telemetry unless you opt out (see the telemetry page); do not expose ports 3100 and 3170 publicly without a reverse proxy and TLS.
• Not a fit for load testing; use a tool such as k6 for that. For heavy mock-server or contract-testing workflows, look at Postman or Bruno.