How to Self-Host Hoppscotch — Open Source Postman Alternative 2026

What Is Hoppscotch?

Hoppscotch is an open source API development platform — think Postman or Insomnia, but built as a web app, significantly faster, and fully self-hostable. It supports REST, GraphQL, WebSocket, SSE, Socket.IO, and MQTT in a single interface.

Postman's Team plan costs $14/user/month. Hoppscotch is free when self-hosted — your team shares collections, environments, and history on your own server.

Key features:

• REST, GraphQL, WebSocket, SSE, MQTT clients
• Team workspaces and shared collections
• Environments (dev/staging/production variables)
• Request history and sync across browsers
• Pre-request scripts and test scripts (JavaScript)
• OpenAPI/Swagger import
• CLI for CI/CD testing (@hoppscotch/cli)
• OIDC/SAML SSO support

---

Prerequisites

• VPS with 1 vCPU, 1GB RAM (Hetzner CX22 ~€3.79/month works)
• Docker + Docker Compose v2
• Domain name with DNS pointing to your server
• SMTP for email verification (required)
• Google/GitHub OAuth app OR email-only setup

---

Docker Compose Setup

Hoppscotch has three components:

• Frontend — the main web interface
• Backend — API and database
• Admin — user and instance management

1. Clone the Repo

git clone https://github.com/hoppscotch/hoppscotch
cd hoppscotch

2. Copy and Configure Environment

cp .env.example .env

Edit .env:

# .env

# --- Database ---
DATABASE_URL="postgresql://postgres:your-password@hoppscotch-db:5432/hoppscotch?connect_timeout=300"

# --- Auth tokens (generate strong random strings) ---
JWT_SECRET="$(openssl rand -hex 32)"
TOKEN_SALT_COMPLEXITY=10
MAGIC_LINK_TOKEN_VALIDITY=3
REFRESH_TOKEN_VALIDITY="604800000"  # 7 days in ms
ACCESS_TOKEN_VALIDITY="86400000"    # 1 day in ms

# --- App URLs ---
VITE_BASE_URL=https://api.yourdomain.com       # backend URL
VITE_SHORTCODE_BASE_URL=https://api.yourdomain.com
VITE_ADMIN_URL=https://admin.yourdomain.com
VITE_APP_TOS_LINK=
VITE_APP_PRIVACY_POLICY_LINK=

# --- Email (required for invite flows) ---
MAILER_SMTP_URL="smtps://username:password@smtp.yourdomain.com:465"
MAILER_ADDRESS_FROM="Hoppscotch <noreply@yourdomain.com>"

# --- OAuth (choose one or multiple) ---

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=https://api.yourdomain.com/v1/auth/google/callback
GOOGLE_SCOPE="email,profile"

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_CALLBACK_URL=https://api.yourdomain.com/v1/auth/github/callback
GITHUB_SCOPE="user:email"

# Email/Password auth (optional, disables OAuth requirement)
ALLOW_SECURE_COOKIES=true

# --- Admin account ---
FIRST_ADMIN_EMAIL=your@email.com

3. docker-compose.yaml

version: "3.8"

networks:
  hoppscotch:

volumes:
  postgres_data:

services:
  hoppscotch-db:
    image: postgres:15
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - hoppscotch
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your-password
      POSTGRES_DB: hoppscotch

  hoppscotch-backend:
    image: hoppscotch/hoppscotch-backend:latest
    restart: always
    networks:
      - hoppscotch
    depends_on:
      - hoppscotch-db
    env_file: .env
    ports:
      - "3170:3170"  # backend API
      - "3000:3000"  # backend admin

  hoppscotch-app:
    image: hoppscotch/hoppscotch-app:latest
    restart: always
    networks:
      - hoppscotch
    env_file: .env
    ports:
      - "3020:8080"  # main app

  hoppscotch-admin:
    image: hoppscotch/hoppscotch-admin:latest
    restart: always
    networks:
      - hoppscotch
    env_file: .env
    ports:
      - "3100:8080"  # admin panel

4. Run Database Migrations

# First, start the database only
docker compose up -d hoppscotch-db

# Run migrations
docker compose run --rm hoppscotch-backend pnpx prisma migrate deploy

# Start everything
docker compose up -d

---

Configure Caddy Reverse Proxy

Hoppscotch uses three subdomains (or you can use path-based routing):

# /etc/caddy/Caddyfile

# Main app
app.yourdomain.com {
    reverse_proxy localhost:3020
}

# Backend API
api.yourdomain.com {
    reverse_proxy localhost:3170
}

# Admin panel
admin.yourdomain.com {
    reverse_proxy localhost:3100
}

systemctl reload caddy

Update your .env to match:

VITE_BASE_URL=https://api.yourdomain.com
VITE_ADMIN_URL=https://admin.yourdomain.com

---

Configure OAuth (Google)

Create Google OAuth App

1. Go to console.cloud.google.com
2. Create a new project (or use existing)
3. APIs & Services → Credentials → Create OAuth 2.0 Client
4. Application type: Web application
5. Authorized redirect URIs:
   https://api.yourdomain.com/v1/auth/google/callback
6. Copy Client ID and Client Secret

Add to .env:

GOOGLE_CLIENT_ID=123456-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-secret

GitHub OAuth

1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App
2. Homepage URL: https://app.yourdomain.com
3. Authorization callback URL: https://api.yourdomain.com/v1/auth/github/callback
4. Generate client secret

Restart After OAuth Config

docker compose down && docker compose up -d

---

First Login: Claim Admin

Visit https://admin.yourdomain.com:

1. Log in with the email matching FIRST_ADMIN_EMAIL
2. The admin dashboard shows user management, invites, and team settings
3. Enable/disable features: allow sign-ins, require invite, email allowlists

Invite your team:

Admin → Users → Invite Users
→ Enter email addresses
→ Team members receive magic link or OAuth invite

---

Use the CLI for CI/CD

Hoppscotch has a CLI for running API tests in your pipelines:

npm install -g @hoppscotch/cli

# Run a collection
hopp test path/to/collection.json \
  --env path/to/environment.json \
  --reporter-junit-export results.xml

Export a collection from Hoppscotch:

Collections → Right-click collection → Export → JSON

GitHub Actions Integration

# .github/workflows/api-tests.yml
name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Hoppscotch CLI
        run: npm install -g @hoppscotch/cli

      - name: Run API Tests
        run: |
          hopp test collections/api-tests.json \
            --env environments/staging.json
        env:
          API_BASE_URL: ${{ vars.STAGING_URL }}
          API_KEY: ${{ secrets.API_KEY }}

---

Writing Test Scripts

Hoppscotch supports pre-request and post-request scripts (JavaScript):

// Post-request test script
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

pw.test("Response has user object", () => {
  const json = pw.response.body;
  pw.expect(json).toHaveProperty("id");
  pw.expect(json.email).toBeDefined();
});

// Set environment variable from response
const token = pw.response.body.token;
pw.env.set("AUTH_TOKEN", token);

This is the same pattern as Postman's test scripts — collections are portable.

---

Hoppscotch vs Postman vs Insomnia

Feature	Hoppscotch (self-hosted)	Postman	Insomnia
Price	~$5/mo server	$14/user/mo	$16/user/mo
Self-hosted	✅	❌	❌
REST client	✅	✅	✅
GraphQL	✅	✅	✅
WebSocket	✅	✅	✅
gRPC	❌	✅	✅
Team workspaces	✅	✅	✅
Environments	✅	✅	✅
Test scripts	✅	✅	✅
OpenAPI import	✅	✅	✅
CLI	✅	✅	✅
Speed	✅ Fast (web app)	⚠️ Electron	⚠️ Electron
Data ownership	✅ Full	❌	❌
Offline mode	⚠️ Limited	✅	✅

---

Backup Hoppscotch Data

#!/bin/bash
# backup-hoppscotch.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/hoppscotch"

mkdir -p $BACKUP_DIR

# PostgreSQL backup
docker compose exec -T hoppscotch-db pg_dump \
  -U postgres hoppscotch | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Clean up old backups
find $BACKUP_DIR -mtime +14 -delete

echo "Hoppscotch backed up: $DATE"

---

Troubleshooting

Backend crashes with "Cannot connect to database":

docker compose logs hoppscotch-backend | head -30
# Ensure DATABASE_URL format: postgresql://user:pass@host:5432/db
# Check hoppscotch-db is healthy: docker compose ps

OAuth login fails:

# Check the callback URL matches exactly
# Google: "https://api.yourdomain.com/v1/auth/google/callback"
# No trailing slashes

# Test OAuth flow:
curl https://api.yourdomain.com/v1/auth/google

App loads but shows "Server unreachable":

# Check VITE_BASE_URL is set to the backend URL (not the app URL)
# App → Backend communication happens in the browser
# VITE_BASE_URL must be publicly accessible

---

Hoppscotch is a popular Postman alternative on OSSAlt — see all open source API development tools.