Deploy Hoppscotch | (Just Updated) Open Source Postman Alternative, API Token and Database Generated
Hoppscotch open source Postman alternative, REST and GraphQL API client
hoppscotch
Just deployed
/data
postgres
Just deployed
/var/lib/postgresql
Deploy and Host Hoppscotch on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the PostgreSQL password, the encryption key and an infra API token are generated, every URL is derived from the deploy's own domain, an administrator is created at first boot, onboarding is closed, and the database sits on a volume. Hoppscotch is the open-source API development platform: a web client for REST, GraphQL, WebSocket, SSE and MQTT requests with collections, environments and team workspaces, an open source alternative to Postman.
About Hosting Hoppscotch
This template runs two services: hoppscotch, the upstream Hoppscotch 2026.10.1 all-in-one image (pinned by digest) through a thin wrapper, and postgres (PostgreSQL 17) with its volume at /var/lib/postgresql. The wrapper also mounts a volume at /data for the web app's signing key. One public domain serves the web app (/), the admin dashboard (/admin) and the backend API (/backend). The listener is on Railway's injected PORT, and the healthcheck is GET /backend/ping.
What the wrapper fixes. A fresh upstream Hoppscotch needs about ten VITE_* URLs and an origin allow-list written by hand, needs its migrations run as a separate step, stops itself once after its first start, and leaves the onboarding endpoint open: the first visitor to /backend/v1/onboarding/config chooses the sign-in providers. The wrapper derives the URLs from RAILWAY_PUBLIC_DOMAIN, applies the migrations, lets the first start finish before the real one, writes the sign-in provider setting so onboarding answers 400, and seeds an administrator and an infra token taken from HOPPSCOTCH_INFRA_TOKEN.
Using it. The infra token drives the instance over REST: list and manage users, invite users, change admin status. Browser sign-in is not enabled by this template: Hoppscotch signs in with an emailed magic link (SMTP) or Google, GitHub or Microsoft OAuth, and both need outside credentials a template cannot generate, so until you configure one (see the self-host documentation linked below) the instance is a closed API: no one can register and no one can log in. The seeded administrator is admin@hoppscotch.local; set HOPPSCOTCH_ADMIN_EMAIL on the hoppscotch service to use your own address. To rotate the token, change HOPPSCOTCH_INFRA_TOKEN and redeploy. Keep DATA_ENCRYPTION_KEY stable: changing it makes stored secrets unreadable.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of thehoppscotchservice); the API base ishttps://RAILWAY_PUBLIC_DOMAIN/backend - Private URL:
http://hoppscotch.railway.internal:8080(the API is under/backend); PostgreSQL atpostgres.railway.internal:5432 - Credentials: the variable
HOPPSCOTCH_INFRA_TOKENon thehoppscotchservice is the infra API token;DATA_ENCRYPTION_KEYencrypts stored secrets and is not a login;DATABASE_URLpoints at thepostgresservice - Auth: send
Authorization: Bearer HOPPSCOTCH_INFRA_TOKENon every/backend/v1/infra/*call. A write with no token answers 401, a write with a wrong token answers 401, and public sign-in answers 404 because no sign-in provider is enabled. - Health:
GET /backend/pingreturns 200
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, HOPPSCOTCH_INFRA_TOKEN (variables of the hoppscotch service); also curl, date, grep. Invites a throwaway address and removes it again.
R="https://$RAILWAY_PUBLIC_DOMAIN/backend"; J="Content-Type: application/json"; A="Authorization: Bearer $HOPPSCOTCH_INFRA_TOKEN"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/ping")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/ping"
# read with the token
curl -s -o /dev/null -w "read users: %{http_code}\n" -H "$A" "$R/v1/infra/users?take=10"
# write with the token: invite a throwaway address, read it back, remove it
E="agent-$(date +%s)@example.com"
curl -s -o /dev/null -w "write invitation: %{http_code}\n" -X POST -H "$J" -H "$A" -d "{\"inviteeEmail\":\"$E\"}" "$R/v1/infra/user-invitations"
if curl -s -H "$A" "$R/v1/infra/user-invitations?take=100" | grep -q "$E"; then echo "read back: found"; else echo "read back: MISSING"; fi
curl -s -o /dev/null -w "delete invitation: %{http_code}\n" -X DELETE -H "$J" -H "$A" -d "{\"inviteeEmails\":[\"$E\"]}" "$R/v1/infra/user-invitations"
# refusals: no token, wrong token, public sign-up, onboarding re-run
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X POST -H "$J" -d '{"inviteeEmail":"intruder@example.com"}' "$R/v1/infra/user-invitations"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X POST -H "$J" -H "Authorization: Bearer not-the-token" -d '{"inviteeEmail":"intruder@example.com"}' "$R/v1/infra/user-invitations"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -X POST -H "$J" -d '{"email":"intruder@example.com"}' "$R/v1/auth/signin?origin=app"
curl -s -o /dev/null -w "onboarding rerun: %{http_code}\n" -X POST -H "$J" -d '{"VITE_ALLOWED_AUTH_PROVIDERS":"GOOGLE"}' "$R/v1/onboarding/config"
Expected output against a fresh deploy (measured on a Railway deploy of this template):
health: 200
read users: 200
write invitation: 201
read back: found
delete invitation: 200
write without key: 401
write wrong key: 401
public signup: 404
onboarding rerun: 400
The refusals are the contract: write without key: 401, write wrong key: 401, public signup: 404 (no one can register) and onboarding rerun: 400 (the first visitor cannot reconfigure sign-in). The first five lines show the token can read and write.
Why Deploy Hoppscotch on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Hoppscotch on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - no deployer fields, a contract block, and one script that proves the instance is healthy, the token can read and write, and unauthenticated writes, sign-up and onboarding re-runs are refused.
- Setup done for you - URLs, migrations, administrator and token are created before the first visitor can reach the instance.
- Onboarding closed - nobody can choose the sign-in providers of your instance.
- Data survives redeploys - users, collections and environments live in PostgreSQL on a volume.
- Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
Common Use Cases
- Self-hosted Postman alternative - keep API collections and environments on your own server.
- Shared API workspace for a team - collections and environments shared between members without a third party.
- API testing for an AI agent - manage the instance over its REST API with the infra token.
- REST, GraphQL and WebSocket debugging - one client for every protocol, from any browser.
Dependencies for Hoppscotch Hosting
- The hoppscotch service and the postgres service with their volumes, created by the template. A custom domain is optional; the wrapper reads
RAILWAY_PUBLIC_DOMAIN.
Deployment Dependencies
Template Content
postgres
postgres:17.10-trixie