Fork of hyper-gateway
Docs: Update differences between upstream
Meta: Update hypercore-fetch-ushin: Purge response has Link header


browse  log 
release notes 



You can also use your local clone with git send-email.

#hyper-gateway-ushin - Fork of hyper-gateway

A gateway for talking to hypercore-protocol using the same URL structures as Agregore.

hyper-gateway-ushin adds features which are useful for building programs using the hyper protocol, but which are outside the scope of the standard Fetch API. New features include:

  • GET "full" directory listing with entry metadata in one request. hypercore-fetch-ushin API
  • Return 403 instead of 404 when requesting a read-only hyperFetch instance for a resource requiring write permissions.
  • Return X-Drive-Size header containing local disk usage of a hyperdrive.
  • Send POST request with Cache-Control: no-store header to clear locally cached blobs for a hyperdrive file or directory.
  • All successful request for content include X-Drive-Version header with latest drive.version.
  • PUT requests which pass a single file return a Content-Length header with the size of the written entry.
  • Responses when purging a drive now include a Link header.


You can download version 3.10.2 of hyper-gateway-ushin from the Codeberg releases page or the SourceHut releases page here for your operating system, move it to your PATH, and make it executable.

The following commands will do this on GNU/Linux systems:

# Paste this into an interactive bash or zsh shell, or save it as a file and run it with sh.

mkdir -p ~/.local/bin/
cd ~/.local/bin/
curl -Lo hyper-gateway-ushin https://codeberg.org/USHIN/hyper-gateway-ushin/releases/download/v3.10.2/hyper-gateway-ushin-linux
# Alternatively, download from SourceHut Builds:
# curl -Lo hyper-gateway-ushin https://git.sr.ht/~ushin/hyper-gateway-ushin/refs/download/v3.10.2/hyper-gateway-ushin-linux
chmod 744 hyper-gateway-ushin


hyper-gateway-ushin run --writable true

Options: hyper-gateway-ushin --help run

hyper-gateway-ushin run

Run the gateway

  --version             Show version number                            [boolean]
  --help                Show help                                      [boolean]
  --writable            Control access to `PUT`       [boolean] [default: false]
  --port                The port to run the server on (HYPE)     [default: 4973]
  --persist             Whether data should be persisted to disk
                                                       [boolean] [default: true]
  --storage-location    The location to store hypercore data
                      [default: "/home/mauve/.local/share/hyper-gateway-nodejs"]
  --silent              Prevent additional logs       [boolean] [default: false]
  --subdomain           Enable serving `example-com.gateway.com/path` as `gatewa
                        y.com/hyper/example.com/path` [boolean] [default: false]
  --subdomain-redirect  Redirect `gateway.com/hyper/domain.here/path` to `domain
                        -here.gateway.com/path`       [boolean] [default: false]


GET http://localhost/4973/hyper/:key/*path

You can load data from the gateway by specifying a Hyperdrive key and a path to a file or folder.

The specific HTTP verbs and headers that are supported can be found in hypercore-fetch. Basically you can replace the hyper:// in a URL with http://localhost:4973/hyper/ and it'll work.

#Subdomain / Subdomain-Redirect

When serving contents on a gateway, some sites may be using absolute URLs (e.g. /script.js) which can be messed up when the data is being served from a subdomain (e.g. http://some-gateway.com/hyper/key_here/).

In order to account for this you can add the --subdomain flag which is based on the IPFS Subdomain Gateway Spec, but applied to hyper.

If your domain is https://example.com, instead of using https://example.com/hyper/blog.mauve.moe/index.html to reference a URL, you can instead use https://blog-mauve-moe.example.com/index.html.

You may also place a hypercore public key into the subdomain to have similar effects.

You can also specify the --subdomain-redirect flag which will automatically perform a 301 HTTP redirect to the subdomain version of a URL when a user attempts to load the /hyper/ path.

#Building native binaries

Hyper-gateway-ushin uses the pkg module to compile the node.js code into a single binary that you can distribute on a server.

  • git clone https://git.sr.ht/~ushin/hyper-gateway-ushin
  • Install node.js if you haven't already
  • npm install
  • npm run build
  • Look in the dist folder for the platform you want.

#Running hyper-gateway-ushin on GuixSD

Build hyper-gateway-ushin-linux with npm run build-linux, then run:

#!/usr/bin/env bash
GATE=~/.local/src/hyper-gateway-ushin/dist  # Use your git clone location

guix shell --container --emulate-fhs --network \
     --expression='(list (@@ (gnu packages gcc) gcc) "lib")' \
     --no-cwd --expose=$GATE --share=$DATA \
     -- $GATE/hyper-gateway-ushin-linux \
     run --writable --persist --storage-location $DATA


#How do I run hyper-gateway-ushin as a background process on GNU/Linux + SystemD?

# Paste this into an interactive bash or zsh shell, or save it as a file and run it with sh.

# This will create the service file.
mkdir -p ~/.local/share/systemd/user/
cat << EOF > ~/.local/share/systemd/user/hyper-gateway-ushin.service
Description=hypercore-protocol gateway daemon (for hyperdrive)

ExecStart=%h/.local/bin/hyper-gateway-ushin --writable true --silent true run

chmod 644 ~/.local/share/systemd/user/hyper-gateway-ushin.service

systemctl --user daemon-reload
systemctl --user start hyper-gateway-ushin.service
systemctl --user status hyper-gateway-ushin.service