Virtualhosts

In the redirection.io agent, Virtualhosts allow to define a configuration for a specific set of domains. This is useful if you want to host multiple websites on the same agent without the need to bind each website to a specific port. The agent will automatically route the requests to the correct backend based on the requested domain, using the Host header of the request.

The virtualhosts configuration is defined under the virtual_hosts key in the agent configuration. Each virtualhost is defined by a list of domains that it should handle, and it allows to specify all the configuration options that usually live under the reverse_proxy key, such as the forward, certificate or trusted_proxies configuration, etc. Here is a configuration example for multiple virtualhosts:

instance:
    name: 'My Instance'
everse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
        - 'tls://0.0.0.0:443'
    forward:
        address: '127.0.0.1:8080'
    agent:
        project_key: DEFAULT_PROJECT_KEY
    certificate:
        acme:
            contacts:
                - myemail@example.com
            directory_url: 'https://acme-v02.api.letsencrypt.org/directory'
    virtual_hosts:
        -
            domains:
                - example.com
                - www.example.com
            agent:
                project_key: WEBSITE_PROJECT_KEY
        -
            domains:
                - 'tls://media.example.com'
            forward:
                directory: /var/www/media
            agent:
                project_key: MEDIA_PROJECT_KEY

The configuration defines two Virtualhosts, one for the example.com and www.example.com domains, and one for the media.example.com domain. Each virtualhost has its own configuration, with different redirection.io project keys.

With such a reverse proxy configuration:

• the agent will accept all incoming connections on ports 80 and 443
• by default, the requests will be handled using the DEFAULT_PROJECT_KEY redirection.io project and forwarded to the backend at 127.0.0.1:8080 in http
• requests to example.com and www.example.com will use the redirection.io project that has the project key WEBSITE_PROJECT_KEY, and will be forwarded to the default forward address (127.0.0.1:8080), in http
• requests received on media.example.com in tls will be sent to a filesystem backend, and associated with the redirection.io project that has the project key MEDIA_PROJECT_KEY

If two Virtualhost configurations overlap, the agent will use the first one that matches the requested domain. For example, if you have a Virtualhost configuration for example.com, and another one for both example.com and www.example.com, then a request made to example.com will use the first VirtualHost, because it is defined first in the configuration file. To avoid this issue, make sure to define your Virtualhost configurations in the correct order, with the most specific ones defined first.

This page has been updated on Apr 16, 2026