Skip to main content


The Lunar architecture consists of several essential components, working together to provide powerful API optimization capabilities. These components include Lunar Proxy, Remedy and Diagnosis plugins, Data Exporters, Lunar Interceptors, and the Discovery tool. Let's delve into each of these components to understand their role within Lunar.

"Modified design elements from [Tool] Cloud Diagram Activity, Figma Community Resources Original resource: Creator: Scaleway Copyright © Scaleway Licensed under CC BY 4.0,"

Lunar Proxy

At the heart of Lunar lies Lunar Proxy, a smart forward-proxy solution. It excels in addressing complex API consumption challenges such as rate limits, retries, and account management. Lunar Proxy can be configured with Remedy and Diagnosis plugin policies to optimize its functionality. By default, Lunar Proxy simply forwards requests to the host specified in the incoming requests. Policies can be defined globally, applying to all requests passing through Lunar Proxy, or on a per-endpoint basis. To achieve optimal performance, Lunar Proxy is intended to run on the same machine as the applications that utilize it.

Remedy Plugins

Remedy plugins are aimed at solving API consumption problems when possible. To do so, they handle requests prior to being forwarded to the actual API provider, and they will also get a hold of responses before these are returned to the caller by Lunar Proxy. Remedy plugins may decide to modify the request or the response (e.g., add or change some header) or even decide to short-circuit on certain requests and return a Lunar-generated response (e.g. when caching plugin kicks in). Of course, they may also do nothing and let the request flow onwards without any modification. Learn more about Remedy Plugins here.

Diagnosis Plugins

Diagnosis plugins have read-only permissions on traffic that reaches them. They cannot affect neither the request nor the response of an HTTP call, and they run in an asynchronous manner, just a bit after the HTTP call has ended. They are meant to assist with visibility and analysis of the traffic. For example, the HAR Extractor Diagnosis Plugin might be used in order to obtain comprehensive information about requests and responses, from which point-on Remedy Plugin Policy configurations can be deducted. They may also help with obtaining metrics regarding HTTP traffic & Lunar's effect on it. Learn more about Diagnose Plugins here.

Data Exporters

While Diagnosis Plugins are responsible for extracting data from HTTP traffic, this data needs to be exporter somewhere in order to be useful. This is the responsibility of Data Exporters: they are meant to be configured & attached to Diagnosis Plugins. For example, we may want to spill the HAR data from the HAR Extractor Diagnosis Plugin to an S3 bucket, or to a local file. Not every Data Exporter may be attached to any Diagnosis Plugin; for further details, see specification per Diagnosis Plugin. Learn more about Data Exporter here.


Lunar Proxy offers a simple tool that helps to validate a successful integration, called Discovery. This tool will record basic metrics (call count and average duration) and aggregate them on an endpoint level. This metrics will be written to a local file, so no prior configuration or integration is required for it to work. It is meant to serve as a simple way to validate Lunar Proxy is handling the traffic is should be handling.

Lunar Interceptors

To allow Lunar Proxy to do its magic, the traffic destined for third-party APIs needs to be routed through it instead of being sent directly to the external world. While it is technically possible to manually modify codebases to achieve this, Lunar offers transparent interceptors as a hassle-free solution. These interceptors can be loaded into the hosting application and take care of intercepting and redirecting traffic to Lunar Proxy with minimal configuration. Our interceptors are designed to have a minimal resources footprint and they also include the Failsafe Mechanism which protects the hosting app from running into issues in the rare case Lunar Proxy is malfunctioning. We offer interceptors supporting various languages and frameworks. For more information, see Interceptors.

Click me for guidance 😀