NPM Install

Globally install with npm

$ npm i -g gagu

You may need command sudo in macOS:

$ sudo npm i -g gagu


All releases

Available Parameters

Show help info:

$ gagu -h
$ gagu --help

Start service:

$ gagu

Start and open in browser:

$ gagu -o
$ gagu --open

Start with HTTPS:

$ gagu -s
$ gagu --security

Start with a specified Host:

$ gagu -H
$ gagu --Host

Start with a specified port:

$ gagu -p 80
$ gagu --port 80

Show version:

$ gagu -v
$ gagu --version

Remove GAGU data directory WORKSPACE/.io.gagu/data:

$ gagu --reset

Remove GAGU root directory WORKSPACE/.io.gagu:

$ gagu --reset-all

Stop service:

# `Ctrl + C` or close terminal

Running Conditions


The running of GAGU needs to provide a local root directory of its own GAGU_PATH.ROOT to store some data.

Every time the service is started, GAGU will detect whether the root directory exists, and if it does not exist, it will automatically create a root directory named .io.gagu in the workspace.

Different platforms will choose different workspaces to create. Here, it is assumed that the user name of the login device is jay:


/data/data/com.termux/files/home/storage/shared points to the internal storage mounted by the Android system, which needs to be obtained through termux-setup-storage in Termux.

For the use of Termux, please refer to Termux Wiki or Termux Advanced Terminal Installation and Configuration Tutorial.

Root Directory

GAGU’s root directory .io.gagu is a hidden folder named at the beginning of ., which can be displayed on the device through specific settings, but will be forcibly filtered in GAGU’s API, even if it has Users with administrator rights cannot access it in GAGU’s Web page.

After the root directory is successfully created, the following subdirectories will continue to be created:

  |- data
  |- log
  |- public
  |  |- avatar
  |  |- image
  |  |- lib
  |- secrets
  |- thumbnail
  |- users
The root directory will be created as `WORKSPACE/` in local development.


When accessing a file that can display thumbnails in GAGU’s File Explorer, GAGU will use the “full path” of the file plus “modification time” to perform md5 operations to obtain a 32-bit string, and then request the thumbnail file with the same name as the string under .io.gagu/thumbnail, if it does not exist, call the thumbnail interface to generate and return.

const { mtimeMs } = statSync(path)
const thumbnailId = md5(`${path}-${mtimeMs}`)

Therefore, when the file does not change (move location or modify), it will take a certain amount of time to obtain the thumbnail for the first time. You can use the “Thumbnail Actively Generating” feature in the “Settings” for the directory containing the thumbnail files that need to be displayed. features to enhance the browsing experience.

GAGU will use ffmpeg and GraphicsMagick interfaces when generating thumbnails, you can decide whether you need to install them, if not, it will not affect the use of GAGU’s main functions, and all files will be displayed with default type icons.

You need to restart GAGU service after you have installed ffmpeg and GraphicsMagick.

Default Port Number

The default port number of the GAGU service is 9293. After the service is started, it can be accessed locally through When accessing other devices in the LAN, replace the IP in it with the intranet IP of the server device.

I assigned a fixed IP to the 13-inch Mac in my home router, and pointed the domain in the hosts of the router to, and started the GAGU service on the Mac with port 80 , now, every device in the LAN can access through a browser to use the GAGU service on the Mac. I also specified the shorter domain for my mobile phone.

There are two ways to modify the port number:

The modification of command parameters has the highest priority, followed by the modification in the settings, and the last is the default port number.

Unrooted Android devices cannot set a port number lower than 1024, which is a pity, because setting port 80 saves the trouble of entering the port number.

Default Account

When starting the service for the first time, GAGU will automatically generate a default account with full permissions.

Username: gagu
Password: 9293

When you log in for the first time, you can only log in with the default account.

It is recommended to change the password immediately after logging in; or create a new account with full permissions and delete the default account.

← Previous

Project Origin

Next →

Feature List ⏳