Hound: a trigram-indexed code search server you run yourself

What Hound solves, and who ends up running it

Hound is a source code search engine you host yourself. The README's own framing is blunt: existing tools were "either too slow, too hard to configure, or require too much software to be installed." Hound's answer is a single Go binary that keeps an index per repository and answers queries through what the README calls a minimal API.

The audience is narrow and specific. It is for teams with a set of repositories that are already reachable over Git, Mercurial, SVN, Bazaar or a local directory, and who want a shared search box instead of everyone cloning everything and grepping. It is also for people who want editor integration: the README lists plugins for Sublime Text, Vim, Emacs and Visual Studio Code, all maintained outside this repository.

It is not a code intelligence tool. Nothing in the README describes symbol resolution, go-to-definition, or cross-repository dependency graphs. It matches text, fast, over an index it maintains.

Trigrams, a Go backend, and a React frontend

The core is credited to Russ Cox's article on regular expression matching with a trigram index, and the repository layout reflects that split. The Go packages are separated into searcher/, index/, codesearch/, vcs/, api/ and config/, with the two binaries built from cmds/houndd and cmds/hound. The UI lives in ui/assets and is compiled by webpack into ui/.build/ui, then copied by the Makefile.

Each configured repository gets a searcher. On startup the README's sample output shows one line per repository ("Searcher started for Hound"), then "All indexes built!", then the server binding. That ordering matters: the process builds indexes before it serves, so a large first run is a wait, not a background warmup.

Keeping indexes current is polling. The README states Hound polls the URL in the config every 30 seconds by default, overridable per repository with the ms-between-poll key. For large repository sets there is a max-concurrent-indexers property to tune. This is a pull model: nothing is pushed to Hound, and changes appear after the next poll, not instantly.

Installing Hound from source and running the first search

The README's build path needs Go (it states a minimum of 1.24, and go.mod declares go 1.24) plus npm. Clone and run make; the Makefile builds the webpack UI first, then compiles both binaries into .build/bin.

git clone https://github.com/hound-search/hound.git
cd hound
make

After that, .build/bin/houndd and .build/bin/hound exist. Next, write a config.json. The README points at config-example.json for the full range of options and default-config.json for this minimal case, which indexes Hound itself:

{
    "dbpath": "db",
    "repos": {
        "Hound": {
            "url": "https://github.com/hound-search/hound.git",
            "vcs-config": {
                "ref": "main"
            }
        }
    }
}

Run houndd from the directory containing that config.json. The README shows output ending in "running server at http://localhost:6080", and the web UI is served there by default. The Docker route is shorter if you would rather not install the toolchain:

docker run -d -p 6080:6080 --name hound -v $(pwd):/data ghcr.io/hound-search/hound:latest

The image's entrypoint is houndd with -conf /data/config.json, which is why the volume mount is required: without a config.json at that path the container has nothing to index.

Private repositories, local paths, and the file:// caveat

The README lists three ways to index private code. The local pseudo-vcs driver indexes a local directory and can be told to watch-changes, which the README describes as computing a recursive hash of all files and re-indexing automatically. SSH-style URLs ("url" : "[email protected]:foo/bar.git") work if the SSH keys are set up on the machine running Hound. The file:// protocol indexes a local clone, but the README is explicit about the cost: polling to keep that clone up to date will not work, and it also does not work for local folders that are not of a supported repository type.

That last point is the sharpest limitation in the documentation. If you point Hound at a plain directory over file://, you get an index that never refreshes. The watch-changes option on the local driver is the documented way around it, and the two are not interchangeable.

Docker adds a path constraint. The README notes that with Docker you must mount a volume to your repository, giving -v $(pwd)/src:/src as the example, and use the relative path to the repo in the configuration.

No TLS, no Windows, and a short release history

The production section of the README is unusually candid. There are no special production flags; --addr=:6880 controls the bind address. On TLS the README states plainly that Hound does not support it, on the grounds that most users run behind Apache or nginx, and that contributions to add it are welcome. If you need the process itself to terminate TLS, this is the wrong tool today.

Platform support is also limited. The README says Hound is only tested on MacOS and CentOS, that it should work on any *nix system, and that Windows is not supported, though it has been heard to compile and run there. On Windows the README suggests excluding the data folder from Windows Search Indexer.

The release history is thin: v0.7.1 in May 2023, v0.7.0 in April 2023, v0.6.0 in September 2022. The repository is not archived and the last push was on 2026-09-10, so work is happening, but the tagged releases are years behind that activity. Anyone pinning to a release tag should expect to be well behind main.

How Hound differs from ripgrep and from hosted code search

The obvious alternative for a single checkout is ripgrep. The difference is architectural rather than a matter of speed claims: ripgrep walks the working tree on every invocation and prints matches to your terminal, while Hound builds a persistent trigram index per repository and answers over HTTP so that many users and editor plugins share one index. ripgrep has no server, no config.json, no polling loop, and no multi-repository model. Hound has all four, which is exactly the overhead you accept in exchange for a shared endpoint.

Against hosted code search services, the difference is where the index lives. Hound keeps it on your machine, next to a dbpath directory, and reads repositories over the protocols you configure, including SSH URLs. The trade is that you own the polling, the nginx or Apache front end, and the upgrades. The README's requirements section reduces the runtime dependency list to one line: Go. Everything else in the Dockerfile (git, subversion, mercurial, breezy, openssh) exists to support the VCS drivers you actually configure.

Licence and the cost of staying current

Hound is MIT licensed, and the LICENSE file is at the repository root. That is permissive and imposes no copyleft obligation on your own code. One inconsistency worth noticing: package.json declares "license": "ISC" for the npm package while the repository-level licence is MIT. The React frontend and its build tooling are devDependencies, so the ISC line covers the JavaScript package metadata, not the Go backend. If your legal review depends on a single declared licence, read LICENSE rather than package.json.

Upgrade cost is dominated by the build, not the binary. The Makefile runs npm install into node_modules/build, then webpack in production mode, then go build for each command; DEBUG switches webpack to development mode. The Dockerfile pins alpine:3.16 and removes the Go toolchain, build-base, rsync and npm after building, which keeps the image small but means you cannot rebuild inside it. Go 1.24 is the floor in go.mod, so a host with an older toolchain will fail at build time rather than at runtime.

Editorial conclusion

Adopt Hound if you want a small self-hosted search endpoint over a known set of repositories and you can build Go 1.24 and npm yourself, or run the ghcr.io/hound-search/hound image. Do not adopt it if you need TLS termination inside the process, Windows support, or a hosted service with no maintenance. Before committing, verify that your config.json parses against docs/config-options.md, that your repositories are reachable over the protocol you chose (git, hg, svn, bzr, local or file://), and that the polling interval you set with ms-between-poll is tolerable for your repo count.

Frequently asked questions

Official sources

1. hound-search/hound on GitHub
2. Issues
3. License: MIT
4. README
5. Releases