Hoverfly: API simulation with a proxy, a CLI and a REST API

What Hoverfly replaces, and who ends up using it

The problem is a dependency you do not control. A payment gateway, an internal service that is only reachable from a staging network, or a third party that rate limits you after twenty calls. Tests that hit those endpoints are slow and fail for reasons unrelated to your code. Hoverfly is a proxy that sits between your application and the real API, so the application keeps making ordinary HTTP calls while the responses come from a simulation you own.

The README frames the audience directly: developers and testers. The listed uses are replacing slow or flaky dependencies, simulating network latency, random failures or rate limits, and exporting simulations so they can be shared and edited. The repository layout backs that up. There is a core/ directory holding the proxy, a hoverctl/ directory holding a separate command line client, functional-tests/ split into core and hoverctl suites, and examples/ with subdirectories for clients, middleware, journal templating, post-serve actions and simulations. That is the shape of a tool meant to be driven from CI and from a developer laptop, not embedded as a library inside a service.

How the proxy, the simulation store and hoverctl fit together

Hoverfly runs as a process that listens for HTTP traffic, decides whether to forward a request to the real destination or answer it from a stored simulation, and records what it sees. The README describes the outputs as API simulations that can be exported, shared, edited and imported, which implies a file format and a store rather than an in-memory mock. The go.mod file lists boltdb/bolt, an embedded key-value store, which is consistent with a local persistence layer for captured traffic.

Two interfaces sit on top of that engine. The REST API is listed as a first-class feature, and hoverctl is a separate binary built from its own directory with its own version string injected at link time. In practice that means a developer can run the daemon on one machine and drive it from another, or script it from a test harness. The Dockerfile exposes ports 8500 and 8888, and the entrypoint passes -listen-on-host=0.0.0.0, so the container is intended to accept connections from outside itself.

The extension point is middleware. The repository has examples/middleware/ and examples/postserveaction/, and the README says simulations can be extended and customized with any programming language. The Makefile notes that some middleware tests need ruby and python installed, which tells you the middleware mechanism is process- or script-based rather than compiled into the Go binary.

Installing Hoverfly and running a first simulation

The README does not contain install commands. Under Quickstart it links to a download and installation page on Read the Docs, and separately to the documentation index. Treat that page as the source of truth for your platform, because the exact archive names and package manager entries are not in the repository README.

If you prefer to build from source, the README gives the sequence. Go must be installed first, and the README warns that if you previously installed Go with apt-get or homebrew you should uninstall those first.

git clone https://github.com/SpectoLabs/hoverfly.git
cd hoverfly
make build

The README states that the resulting binaries land in the target directory. The Makefile confirms this: it builds core/cmd/hoverfly into target/hoverfly and hoverctl into target/hoverctl. You should see both files there after a successful build.

The README also documents a Docker-based path. The Dockerfile builds a statically linked binary into an alpine:3.20 image, and its entrypoint already binds to all interfaces.

ENTRYPOINT ["/bin/hoverfly", "-listen-on-host=0.0.0.0"]
EXPOSE 8500 8888

Those two lines are the container contract: the image declares ports 8500 and 8888 and starts Hoverfly listening on every interface. Which port serves which interface is not stated in the README, so check the Read the Docs pages before wiring a client to one of them.

For the first real use, the workflow the README implies is: point your application's HTTP client at the proxy, let Hoverfly record the traffic your application generates, then export that recording as a simulation and import it later so the same requests are answered without the upstream service. The examples/simulations/ directory in the repository is the place to look for the shape of a simulation file.

Where Hoverfly is the wrong tool

The scope is HTTP and HTTPS. The topics list includes mitm and the go.mod pulls in a fork of goproxy, which is a forward proxy library. Nothing in the repository suggests gRPC, message queues, database protocols or raw TCP simulation, and the README does not claim them. If your dependency is not reachable over HTTP, this is not the project for you.

The operational cost is the second constraint. Hoverfly is a separate process, and in container form a separate container, that has to be started before the tests and pointed at by the application. That is a configuration change in every environment where you want the simulation active. A test that stubs an interface in-process needs none of that, and for a single narrow dependency inside a unit test, the proxy is heavier than the problem.

The third is middleware. The README says you can extend simulations with any programming language, and the Makefile warns that some middleware tests fail without ruby and python present. If you plan to run middleware inside the Alpine image, verify that the interpreter you need is actually in that image; the Dockerfile shown here copies certificates and the binary, and does not install language runtimes.

Finally, the documentation is split. The README is a landing page. Installation, the simulation format, the REST API and the middleware contract all live on the Read the Docs site, and the README does not restate them. Budget for reading that site rather than expecting the repository to answer questions.

Hoverfly against WireMock and against in-process stubs

WireMock is the closest comparison in the API mocking space, and the difference is in how the simulation is produced. WireMock's model centers on hand-authored stub mappings: you describe request matchers and responses, and the server answers them. Hoverfly's README leads with recording real traffic and exporting it as a simulation, which makes the capture-then-replay path the primary one. Both can be authored by hand, but the starting point differs, and that shapes how much work it is to get a first simulation running against an unfamiliar API.

The second difference is the client surface. Hoverfly ships hoverctl as a separate binary and a REST API, and the README also lists native language bindings for Java. A team that wants to configure mocks from inside a JUnit test has a documented path. Teams in other languages drive the REST API or shell out to hoverctl.

Against in-process stubs, the trade is straightforward. A stub replaces a client object inside your test process, which is fast and needs no ports. Hoverfly replaces the network, which means the code under test is unmodified and the same simulation works for a service written in any language. That matters when the thing you are testing is not the client call but the behavior around it, such as retry logic, or when the application is not written in the language your tests are.

Licence, maintenance and what an upgrade actually costs

Hoverfly is Apache License 2.0, and the README links to the LICENSE file in the repository. The README also carries a copyright line naming Hoverfly Cloud, and the project is described as developed and maintained by iOCO Solutions. There is a commercial offering, Hoverfly Cloud, linked from the README, which is a separate service rather than a licence restriction on the open source tool. Apache 2.0 permits commercial use and modification; the usual obligations around notices and attribution apply, and anything beyond that is a question for your own legal review, not something this article can settle.

The repository is not archived, and the last push was on 2026-09-28. Releases have been frequent: v1.12.13 on 2026-08-28, v1.12.14 on 2026-09-13, and v1.12.15 on 2026-09-21. That cadence is the main signal that the project is being worked on.

Upgrade cost is dominated by the simulation format and the middleware contract, not by the binary. The README presents export and import as core features, which means simulations are portable artifacts you will keep in version control. If a release changes how a simulation is interpreted, your stored files are what break, and the README does not document a migration path for them. The Makefile's update-version target and the build-release.sh script suggest the maintainers manage versions themselves rather than through a package manager you can pin. Pin the container image tag or the binary version you tested, and re-run your simulation suite before moving that pin.

Editorial conclusion

Adopt Hoverfly if you need to stand in for an HTTP dependency without editing application code, and if you are comfortable working from the Read the Docs site because the README itself only points there. Do not adopt it for protocols outside HTTP and HTTPS, or if you expect the repository to hand you an install command: it does not. Before committing, verify the download and installation page for your platform, confirm which port your client will be pointed at, and check that your middleware language is present in the image if you plan to run in Docker.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. SpectoLabs/hoverfly on GitHub