Hoverfly takes a config object, which contains sensible defaults if not configured. Ports will be randomised to unused ones, which is useful on something like a CI server if you want to avoid port clashes. You can also set fixed port:


You can configure Hoverfly to process requests to certain destinations / hostnames.

localConfigs().destination("") // only process requests to
localConfigs().destination("api") // matches destination that contains api, eg.
localConfigs().destination("") // matches destination by regex, eg. or

You can configure Hoverfly to proxy localhost requests. This is useful if the target server you are trying to simulate is running on localhost.


You can configure Hoverfly to capture request headers which is turned off by default:

localConfigs().captureHeaders("Accept", "Authorization")

You can configure Hoverfly to run as a web server on default port 8500:


You can configure Hoverfly to skip TLS verification. This option allows Hoverfly to perform “insecure” SSL connections to target server that uses invalid certificate (eg. self-signed certificate):


If you are developing behind a cooperate proxy, you can configure Hoverfly to use an upstream proxy:

localConfigs().upstreamProxy(new InetSocketAddress("", 8900))


Hoverfly logs to SLF4J by default, meaning that you can control log level using standard logging configuration. Here is an example logback.xml that set Hoverfly log level to WARN:

<?xml version="1.0" encoding="UTF-8"?>

<configuration scan="false" debug="false">

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <Pattern>%date{ISO8601} [%-5level] %logger{10} %msg%n</Pattern>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    <logger name="hoverfly" level="WARN">
        <appender-ref ref="CONSOLE" />


You can override the default hoverfly logger name:


Or change the log output directly to stdout:



You can configure Hoverfly to use a local middleware (for more details, please check out Hoverfly Middleware):

localConfigs().localMiddleware("python", "middleware/")

You should provide the absolute or relative path of the binary, in this case, python for running the python middleware. The second input is the middleware script file in the classpath (eg. test/resources folder)


When requests pass through Hoverfly, it needs to decrypt them in order for it to persist them to a database, or to perform matching. So you end up with SSL between Hoverfly and the external service, and then SSL again between your client and Hoverfly. To get this to work, Hoverfly comes with it’s own self-signed certificate which has to be trusted by your client. To avoid the pain of configuring your keystore, Hoverfly’s certificate is trusted automatically when you instantiate it.

Alternatively, you can override the default SSL certificate by providing your own certificate and key files via the HoverflyConfig object, for example:


The input to these config options should be the file path relative to the classpath. Any PEM encoded certificate and key files are supported.

If the default SSL certificate is overridden, hoverfly-java will not automatically set it trusted, and it is the users’ responsibility to configure SSL context for their HTTPS client.

Using externally managed instance

It is possible to configure Hoverfly to use an existing API simulation managed externally. This could be a private Hoverfly cluster for sharing API simulations across teams, or a publicly available API sandbox powered by Hoverfly.

You can enable this feature easily with the remoteConfigs() fluent builder. The default settings point to localhost on default admin port 8888 and proxy port 8500.

You can point it to other host and ports


Depends on the set up of the remote Hoverfly instance, it may require additional security configurations.

You can provide a custom CA certificate for the proxy.

    .proxyCaCert("ca.pem") // the name of the file relative to classpath

You can configure Hoverfly to use an HTTPS admin endpoint.


You can provide the token for the custom Hoverfly authorization header, this will be used for both proxy and admin endpoint authentication without the need for username and password.

    .withAuthHeader() // this will get auth token from an environment variable named 'HOVERFLY_AUTH_TOKEN'

    .withAuthHeader("some.token") // pass in token directly