Self-Host ghfind with Localtonet HTTP Access

What you are self-hosting

ghfind is an evidence-based developer discovery and GitHub profile scoring application. A user submits a public GitHub handle, and the application evaluates public account activity to produce a value and trust score from 0 to 100. The scoring model considers six dimensions: account maturity, original project quality, contribution quality, ecosystem impact, community influence, and activity authenticity. It also checks for farming-related warning signals intended to distinguish sustained engineering work from easily inflated metrics.

The base score is deterministic and is computed on the server. ghfind also supports an optional language-model workflow in two separated passes. A bounded judge pass may calibrate a score within a limited range, while a writer pass creates report text and tags without changing the fixed result. The deterministic scoring path does not require an LLM. Because the documented environment-variable names for every optional model provider are not included in the available installation evidence, this guide does not invent them. If you want optional generated reports, use the variable names and provider instructions present in the version of .env.example that you checked out.

The same application exposes several surfaces. The browser interface is useful for interactive searches and reports. The REST API supports programmatic scoring. The MCP endpoint lets compatible AI clients use ghfind tools through Streamable HTTP. These surfaces run behind the same local Next.js HTTP service, which is why one Localtonet HTTP tunnel can provide remote transport to the application.

How requests move through the application

A browser scoring request is sent to ghfind's server-side API. The server obtains public GitHub information through GitHub's REST and GraphQL interfaces using the operator's configured token, runs the scoring logic, and may write cache or database state. The repository documentation describes Redis as optional in this flow, so a separate Redis deployment is not part of the basic local installation documented here.

This separation matters for security. A visitor does not need to receive your GitHub token in order to request a score. The token belongs in the server's local environment file and must remain on the machine running ghfind. Remote visitors communicate with ghfind, and ghfind communicates with GitHub.

Prerequisites and planning

Prepare the host before cloning the repository. The machine must be able to reach GitHub over outbound HTTPS, run the Node.js toolchain required by the checked-out ghfind version, and run pnpm. You also need Git if you plan to clone the repository from its upstream URL. The exact supported Node.js and pnpm versions were not established in the supplied project evidence, so this article deliberately does not guess them. Check the repository's current package metadata, package-manager declaration, lockfile, and any engine constraints before choosing versions.

You also need a GitHub personal access token for the server-side GITHUB_TOKEN setting. Create and manage that token through GitHub, grant only the permissions required by the ghfind version you are deploying, and do not paste it into terminal history, screenshots, support messages, source control, or a public tunnel configuration. The available evidence does not specify a universal scope set, so we cannot safely prescribe scopes that might be excessive or insufficient.

Choose the Localtonet client location

The simplest arrangement is to run ghfind and our client on the same machine. In that case, the HTTP tunnel can target 127.0.0.1 on port 3000, matching the documented local ghfind endpoint. If our client runs on another device, that device must be able to reach ghfind over the local network, and ghfind must listen on an address reachable from that device. The supplied ghfind evidence does not document a supported bind-address flag, so this guide does not invent one. Use the same-host arrangement unless the current project documentation explicitly establishes a different binding procedure.

Decide who should be able to use the deployment

The upstream score API is described as requiring no caller authentication. That statement concerns the ghfind application endpoint, not the security of your GitHub token. It also means that placing your self-hosted service on a public URL can make the scoring route callable by anyone who knows the address unless you add an independently verified access-control layer.

Before creating a tunnel, decide whether the deployment is intended for public sharing, a controlled team integration, or temporary testing. A tunnel solves reachability. It does not automatically add application-level authorization to a route that does not implement it.

Install the ghfind source and dependencies

The following sequence follows the project's documented pnpm installation path. Run it from a terminal under the operating-system account that will own the application files.

git clone https://github.com/hikariming/ghfind.git
cd ghfind
pnpm install
cp .env.example .env.local

On Windows PowerShell, the equivalent file-copy operation is:

Copy-Item .env.example .env.local

Do not remove variables from the example file merely because this guide does not discuss them. The template belongs to the checked-out ghfind release and is more current than a static article. Review its comments, keep required settings, and change only values you understand.

Configure GitHub access and initialize local D1

Open .env.local in a local text editor and assign your GitHub token to the documented variable. The line has this form:

GITHUB_TOKEN=your_github_token_here

Replace the placeholder locally. Do not include quotation marks unless the current example file specifically requires them, and do not copy the completed line into logs or issue reports. Optional LLM settings should also come from the checked-out .env.example. We do not provide guessed model-provider variable names because those details can change and were not fully established by the supplied evidence.

Apply both local database migrations

ghfind uses Wrangler's local D1 emulator for the documented development workflow. Two local D1 databases must receive their migrations before database-backed features are used. Run both commands from the repository root and preserve their documented order:

pnpm exec wrangler d1 migrations apply ghfind --local
pnpm exec wrangler d1 migrations apply ghfind-feed-dev --local

The first command applies migrations to the local ghfind database. The second initializes the local ghfind-feed-dev database. The --local option is important because this workflow is meant to use the local emulator. According to the project documentation, local development never connects to Cloudflare and does not require wrangler login.

Local D1 state persists under:

.wrangler/state/v3

That directory is operational data, not a substitute for the migration files in source control. Preserve it if you need to retain local records between restarts. Before copying it for an operator-managed backup, stop the application so files are not changing during the copy. The project evidence does not define a formal production backup and restoration procedure, so test any backup process before depending on it.

Start the development server

After the environment file and migrations are ready, start ghfind:

pnpm dev

Keep the terminal open while testing. The documented local host value is http://localhost:3000. If the terminal reports a startup error or a different address, trust the running version's output and resolve that discrepancy before creating a tunnel.

Verify the browser, REST API, and MCP surfaces locally

Do not expose ghfind remotely until all required local surfaces work. Local verification separates application problems from tunnel problems and gives you a known-good target for Localtonet.

Verify the browser application

On the ghfind host, open:

http://localhost:3000

Confirm that the page loads without a server error. Submit a public GitHub username through the interface and watch the terminal for failures. A rendered home page alone does not prove that the GitHub token, API calls, migrations, and scoring path all work, so complete an actual profile request.

Verify the deterministic REST score route

The documented REST route is /api/score/{username}. The following request uses the public octocat account as a replaceable example:

curl -i http://localhost:3000/api/score/octocat

A working route should return an HTTP response containing API output rather than a connection failure, an unhandled server error, or an HTML framework error page. The exact JSON schema can evolve, so integrations should follow the OpenAPI document supplied by the running ghfind release rather than depending on fields guessed by this article.

Although the score route does not require caller authentication, the local server still uses its configured operator token when retrieving GitHub data. If the browser shell loads but this request fails, inspect the ghfind terminal first. Invalid credentials, API limits, missing environment settings, and upstream connectivity are application-layer issues rather than Localtonet tunnel issues.

Verify the MCP endpoint correctly

The MCP endpoint is available at:

http://localhost:3000/mcp

MCP over Streamable HTTP is a protocol endpoint, not necessarily a human-readable web page. Opening it in a browser or sending an arbitrary GET request may not constitute a valid MCP test. Configure a compatible MCP client to use the URL, initialize a session according to that client's supported Streamable HTTP workflow, and invoke one of the tools exposed by your running ghfind version.

The project's public documentation describes tools for scoring and scanning users, comparing accounts, retrieving leaderboards, and searching users. Tool names and schemas are part of the running MCP implementation, so let your MCP client discover them rather than hardcoding an unverified request body.

Build and run ghfind outside development mode

The development server is appropriate for installation checks and local iteration. The project also documents a production build and start path using the package scripts:

pnpm build
pnpm start

Run the build from a clean, configured checkout. If it fails, fix the reported type, dependency, configuration, or build error rather than exposing the development server as a workaround. Once the build succeeds, start it with pnpm start and repeat every local verification test. A successful development run does not guarantee that the production build has the same configuration or runtime behavior.

The available evidence also mentions pnpm start as a documented run option. Package scripts can evolve, so inspect the current package.json before automating startup. This guide can confirm the documented commands, but it cannot establish an unsupported process-manager configuration, operating-system service file, container deployment, restart policy, or cloud D1 production architecture.

Routine operation

For an interactive run, stop the foreground process with the terminal's normal interrupt action, commonly Ctrl+C. Stop the Localtonet tunnel separately when remote access is no longer required. Remember that creating a tunnel in our dashboard does not mean it is running, and stopping ghfind does not automatically delete its tunnel configuration.

When updating ghfind, preserve your environment configuration and local data, fetch or check out the intended release, install dependencies according to the lockfile, review new environment settings, apply pending local migrations, rebuild if appropriate, and verify locally before restoring public access. Avoid performing an unreviewed source update directly against an internet-accessible instance.

What this setup does not claim

A successful pnpm build and pnpm start provides a production-mode application process, but it does not by itself create a fully hardened production service. A durable deployment may also require supervised restarts, operating-system patching, log handling, resource controls, tested backups, access restrictions, and monitoring. Those controls depend on your environment and are not defined by the supplied ghfind installation evidence.

Expose the working ghfind service with Localtonet

Once http://localhost:3000 works on the host, Localtonet can provide a public HTTP address for the service. Our client establishes an outbound connection to a Localtonet relay server, so you do not need to configure inbound router port forwarding, obtain a public IP address, modify the router firewall, or set up a VPN.

An HTTP tunnel is the appropriate tunnel family because ghfind serves its browser application, REST routes, OpenAPI document, and MCP Streamable HTTP endpoint through one HTTP service. The public URL keeps the same path structure. For example, if the assigned public origin is represented as https://your-assigned-address, the score route is under /api/score/{username} and the MCP endpoint is under /mcp. Use the actual URL assigned by the dashboard rather than copying this illustrative placeholder.

For the current product interface and documented field sequence, review our HTTP tunnel documentation while creating the tunnel. Exact server selections, subscription availability, and domain options can change, so the live dashboard is authoritative for the choices available to your device.

Remote verification sequence

Begin with the public root URL in a browser. Then append the REST path and test a known public username. Finally, update your compatible MCP client from the local endpoint to the public /mcp URL and perform a protocol-level initialization. Testing in this order makes failures easier to isolate.

If the home page works remotely but an API route fails, the HTTP tunnel is generally reaching the application and the problem is likely route-specific or upstream. If every public path fails while local tests continue to work, inspect the Localtonet client connection, tunnel state, selected device, target IP, and target port.

Security and exposure checklist

Internet reachability changes the risk profile of a local application. ghfind consumes a server-side GitHub token, performs outbound API calls, and exposes routes that can trigger work. The upstream score endpoint is documented as unauthenticated for callers, so do not assume that possession of the URL provides meaningful access control.

Also consider the privacy boundary of the data itself. ghfind evaluates public GitHub signals. Private organizational work is not visible to the scoring engine, so a score represents a public footprint rather than a complete judgment about a person's engineering ability or contribution quality. If you integrate scores into review workflows, use them as one input and retain human review.

Troubleshooting installation and remote access

Use a layer-by-layer diagnostic order

Start with the process itself. Confirm that ghfind is running and that the terminal does not show an immediate exception. Next, test the root page on localhost. Then test the REST route locally. After that, test MCP with a compatible client. Only when those checks pass should you investigate the public URL.

For the tunnel layer, verify that our client is connected, the intended device token is selected, the tunnel is running, and the target matches the local service. Avoid changing application settings and tunnel settings at the same time. One controlled change followed by one test gives you clearer evidence than several simultaneous changes.

Frequently asked questions