Fetch GitHub Hosts client and server modes

Why Fetch GitHub Hosts targets hosts-file access problems

Fetch GitHub Hosts addresses a specific form of slow or unreliable GitHub access: the public DNS response for a GitHub domain may not be suitable on the user's current network. Its intended users are researchers, students, and other people described by the README as needing a way to synchronize GitHub-related host mappings. Instead of asking users to edit DNS records repeatedly by hand, the application can retrieve a prepared hosts document, add it to the operating system's hosts file, and repeat that process on a configured interval.

The repository describes two distinct operating models. Client mode consumes a remote hosts source and updates the local system file. Server mode does not update the current machine's hosts file. It starts a local HTTP service that resolves GitHub domains and exposes the resulting records as `hosts.txt` or `hosts.json`, which other devices can consume. That split makes the project relevant both to a laptop user and to someone operating a small local service for several machines.

This approach is deliberately tied to static host mappings. It does not provide a conventional local DNS resolver in the documentation, and it does not describe certificate management, domain discovery, or checks that prove that a GitHub address belongs to a legitimate service. It is therefore best understood as a synchronization utility for known GitHub-related records, not as a general-purpose network repair tool.

Fetch GitHub Hosts architecture and record flow

The repository layout identifies a Nuxt and Vue user interface backed by Tauri 2 under `src-tauri/`. Relevant package dependencies include `@tauri-apps/api`, `@tauri-apps/cli`, and `@tauri-apps/plugin-shell`. This structure is consistent with a cross-platform desktop application that presents a graphical interface while invoking operating-system capabilities for hosts-file updates, elevation, and server startup.

In client mode, the documented data flow starts with a remote URL. The default is `https://hosts.gitcdn.top/hosts.txt`, while Github520 and a user-defined URL are also identified as source choices in the graphical interface. The application retrieves the current records, then writes the relevant content into the system hosts file. The README says that the first write requires one-time authorization and that further writes during the same session do not require another password entry. On Unix-like systems, the launch examples still use `sudo`, which places the authorization boundary at the operating system rather than inside Fetch GitHub Hosts.

In server mode, the application starts an HTTP listener, by default on port `9898`. It exposes plain text and JSON representations and includes a web page with light and dark themes and multiple languages. The documented endpoints are `/hosts.txt` and `/hosts.json`. A client on another device can therefore point `--url` at `http://127.0.0.1:9898/hosts.json`, although that address is local to the device running that command and is not a network address for another machine. The README does not document authentication, access control, or deployment beyond the local server workflow.

Installing the packaged desktop application

The README directs users to the GitHub Releases page rather than documenting installation from the source tree. Releases provide a Universal `.dmg` for macOS on Intel and Apple Silicon, x86_64 `.msi` or `.exe` packages for Windows, and x86_64 `.deb` or `.AppImage` files for Linux. The available application entry point is the package named `fetch-github-hosts`; no separate installation command is documented in the repository instructions.

After installing the package for the relevant platform, run the desktop application to reach its graphical interface. Leaving `--mode` unspecified starts the GUI. The interface can select client or server behavior, choose among the documented sources, provide a custom remote URL, and set the automatic retrieval interval in minutes. It also provides controls described as background tray support and one-click start or stop.

The repository includes Nuxt and Tauri build scripts, but the README does not give a complete source-build tutorial with prerequisites, signing requirements, native dependency setup, or platform-specific packaging commands. Based on `package.json`, development and packaging are represented by `npm` scripts such as `nuxt dev`, `tauri dev`, and `tauri build`, but the official installation path documented for users is the prebuilt release package. A first check should therefore be whether the release page contains the required platform and architecture.

Starting client mode for a scheduled hosts update

The shortest documented client launch uses the default source and a 60-minute retrieval interval. Run the executable with `client` mode and grant the operating-system authority needed to modify the hosts file. On Linux and macOS, the README uses `sudo`; Windows launches `fetch-github-hosts.exe` directly.

The following commands start the client with the default URL. On Unix-like systems, `sudo` allows the application to write the protected hosts file. A Windows user should run the corresponding executable in an elevated context if the operating system requests it.

sudo ./fetch-github-hosts -m client

fetch-github-hosts.exe -m client

The README also documents a 10-minute interval and a custom source. The interval changes how often Fetch GitHub Hosts fetches records. The custom URL example points client mode at the JSON endpoint exposed by a server on the same machine at port `9898`.

sudo ./fetch-github-hosts -m client -i 10

sudo ./fetch-github-hosts -m client -u http://127.0.0.1:9898/hosts.json

Because `-u` accepts a remote URL, source selection is also a trust decision. The documentation lists FetchGithubHosts, Github520, and custom URLs, but it does not explain record validation, signature verification, or rollback of a previous hosts file. Review the source and preserve a separate system backup before allowing automatic replacement.

Serving records from Fetch GitHub Hosts server mode

Server mode turns the same application into an HTTP distribution service. The default listener is port `9898`, and the documented resources include `hosts.txt`, `hosts.json`, and a web interface. Unlike client mode, this command does not need `sudo` because the documented server action is to listen for HTTP requests and resolve GitHub domains, not to rewrite `/etc/hosts`.

Start the default server with one of these documented commands:

./fetch-github-hosts -m server

fetch-github-hosts.exe -m server

Port `9898` is the documented default, while `6666` is the example for a custom port. A custom HTML template can be supplied with `--template`; the README states that it recognizes `{{FGH_VERSION}}` and `{{FGH_UPDATE_TIME}}`.

./fetch-github-hosts -m server -p 6666

./fetch-github-hosts -m server -t /path/to/template.html

The server's practical value depends on trust and network placement. The README does not document authentication, HTTPS, TLS certificates, per-client authorization, or a production reverse-proxy configuration. It also does not explain how the server discovers or refreshes GitHub domain records. For a private network, the administrator would need to decide separately which clients may connect and how the service is exposed; neither control is built into the documented interface.

Hosts-file and DNS-cache limitations of the manual route

For users who do not want to run the packaged client, the README documents a manual fallback. The contents of `https://hosts.gitcdn.top/hosts.txt` can be pasted into `/etc/hosts` on Linux and macOS or `C:\Windows\System32\drivers\etc\hosts` on Windows. After editing, the operating system's DNS cache may need to be flushed.

These commands use the documented operating-system commands for each platform:

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

ipconfig /flushdns

sudo systemd-resolve --flush-caches

The `systemd-resolve` command may not exist on every Linux installation, but the README does not define behavior for distributions that use a different resolver. A shell example can replace records beginning at a marker and append the downloaded file, but it is only shown in the README and no rollback procedure is supplied. That is a meaningful constraint. Hosts files are shared with other services and administrators, and a malformed or stale source can affect more than GitHub access.

The documented manual operation also does not cover duplicate markers, preserved user entries, permissions, or conflict detection. For that reason, automated client mode should not be treated as equivalent to replacing a managed network policy. It is a targeted synchronization mechanism with a high-privilege side effect.

Release cadence, GPL-3.0, and upgrade exposure

The repository is not archived, and the last push was on 2026-08-26. The release history lists `v4.1.0` on 2026-08-26, followed by `v4.0.3` and `v4.0.2` on 2026-02-14. These dates indicate recent repository activity, but the README does not provide a compatibility policy, migration guide, changelog detail, or rollback procedure for application settings. Upgrading from one release to another therefore requires checking the release notes and preserving the current hosts file independently.

The repository identifies `GPL-3.0` as its license. That matters for distribution and modification workflows, especially when the application is bundled with other software or changed before redistribution. This review does not interpret the license or provide legal advice. The practical engineering question is whether the release artifact, source modifications, and distribution arrangement match the obligations and approval requirements applicable to the organization using it.

The repository's primary language is listed as HTML, while `package.json` describes a Nuxt 4 and Vue 3 interface with Tauri 2 desktop dependencies. The `dev`, `build`, `preview`, `tauri`, `tauri:dev`, and `tauri:build` scripts show the intended development layers. The README focuses on packaged applications rather than reproducible source builds, so operators should verify artifact provenance and platform availability before making the utility part of a managed endpoint workflow.

Editorial conclusion

Fetch GitHub Hosts fits individual users on macOS, Windows, or Linux who need a scheduled hosts update, and self-hosters willing to operate an HTTP service and maintain a trusted record source. It is a poor fit for managed workstations where administrators prohibit hosts-file changes, or for networks that require a formally controlled DNS architecture. Before adoption, verify that writes to `/etc/hosts` or `C:\Windows\System32\drivers\etc\hosts` are permitted, decide which source is trusted, and confirm that the selected platform package and scheduled interval meet the deployment requirements.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Licoy/fetch-github-hosts on GitHub
3. Project website
4. README
5. Releases