Route requests through Lightyear
Lightyear is a mode of the LLM Router plugin. When you attach it to an LLM route, requests go to the Lightyear service first and then to the model provider. Lightyear applies cache optimizations and a code mode, with the aim of reducing LLM spend. This topic shows you where to find Lightyear mode, how to turn it on, and how to use it.
Lightyear is experimental and in development. Its behavior can change, and results such as cost savings can vary. Test it on your own workloads before you rely on it.
Prerequisites
Before you begin, make sure you have the following:
- An LLM route to Anthropic, OpenAI, or Google Gemini that accepts authenticated requests. Gemini works only with Use the client’s provider credentials turned on. For the steps, see Connect an LLM provider.
- A route with exactly one LLM connection.
- Permission to create plugin instances.
- A gateway key for the route.
Understand Lightyear mode
Lightyear isn’t a separate plugin. It’s one of the modes of the LLM Router plugin, alongside single, fallback, and loadbalance. You can attach it to an LLM route whose connection goes to Anthropic, OpenAI, or, with client credentials, Google Gemini. The gateway rejects Lightyear mode for other providers.
Without Lightyear, a request on a route goes straight to the provider that you connected. With Lightyear mode on, the same request goes to the Lightyear service, which forwards it to the provider.
Lightyear is designed for long conversations, such as sessions with a coding agent like Claude Code, where many requests build on each other. A single request sent from a REST client is unlikely to show an effect.
Turn on Lightyear mode
To turn on Lightyear mode, do the following:
- Click Plugins, find LLM Router in the Routing category, and select Use.
- Enter a Name, for example
lightyear-router. - Set Scope kind to
route, and set Scope name to the route you want to configure. The LLM Router can be scoped only to a route. - For Mode, select
lightyear. - Decide whether to turn on Use the client’s provider credentials. For more information, see the next section.
- Click Save.
The route’s row on LLMs > Routes then lists the plugin instance under Plugin instances.
Choose how the route authenticates to the provider
The Use the client’s provider credentials toggle controls whose credentials reach the provider:
If you turn the toggle on and send a request without provider credentials, the provider rejects it. For example, Anthropic returns an authentication_error that says the x-api-key header is required.
Send traffic through the route
After you save the instance, requests on the route use Lightyear. To test with Postman, send a request with your gateway key. If the toggle is on, also add the provider’s key in the provider’s header.
To use Lightyear from a coding agent, point the agent at the route, as the next section shows. With the toggle on, the agent signs in as usual and passes its own credentials through.
Point a coding agent at the route
Coding agents are where Lightyear helps most, because their sessions are long. Select your agent, and add the gateway as its provider. Replace BASE_URL with the base URL of your Lightyear route and GATEWAY_KEY with your gateway key. To get the base URL of a route, select Copy LLM base URL on LLMs > Routes.
Claude Code
Codex
Add the following to ~/.claude/settings.json, or to .claude/settings.json in a project, and then restart Claude Code:
With Use the client’s provider credentials off, the gateway adds the Anthropic key saved on the connection. With it on, Claude Code sends its own sign-in token, so you don’t set an API key.
For more information, see Use Claude Code with Fabric AI Gateway.
Treat the gateway key as a secret. Don’t commit a settings file that contains it.
Confirm that requests use Lightyear
To confirm that requests go through Lightyear, open Traces. A request on the route shows a request to the Lightyear service, followed by the request to the provider. A request on a route without Lightyear shows only the request to the provider.
Review Lightyear savings
When an enabled LLM Router instance in lightyear mode exists in the namespaces you’re viewing, the LLM tab of Analytics shows a Lightyear savings card. To open it, select Analytics in the sidebar (or Admin > Analytics for the whole organization), and then select the LLM tab. The card estimates what Lightyear saved compared with the same sessions calling the provider directly. It shows the following:
If no Lightyear sessions ran in the selected window, the card says No Lightyear sessions in the selected window. The card doesn’t appear when no enabled Lightyear instance exists in the namespaces you’re viewing.
The figure is a heuristic estimate, and it uses standard list prices without your organization’s discounts. Because Lightyear is experimental, treat it as a guide, and compare it with the token usage and cost on the rest of the LLM tab.
Next steps
- Review token usage and estimated cost on the LLM tab of Review analytics.
- Combine Lightyear mode with a rate limit on the same route. For the steps, see Control traffic with plugins.

