NyaProxy: A Key-Injecting Gateway for HTTP APIs
NyaProxy acts like a smart, central manager for accessing various online services (APIs) – think AI tools (like OpenAI, Gemini, Anthropic), image generators, or almost any web service that uses access keys. It helps you use these services more reliably, efficiently, and securely.
At a glance
- What is it?
- NyaProxy is a Python API gateway that holds upstream credentials, rotates them across a pool, and enforces rate limits and retries. It fits teams juggling several keys for one provider, and it is the wrong tool if you need per-user accounting or a hardened internet-facing edge.
- Who is it for?
- Adopt NyaProxy if your application code is scattered with provider keys, you already run several keys per provider, and you want one binary to own rotation, rate limits, and retries. Do not adopt it if you need per-end-user quotas, a hardened public edge, or a proxy that does not restart on every config change.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 57 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: provider keys spread across services
Most teams end up with the same shape of problem. An application needs OpenAI, Gemini, or Anthropic, plus maybe an image API and a data vendor. Each one has its own key, its own rate limit, and its own failure mode. The keys get pasted into environment variables across several services, and when one key hits a quota, someone edits a secret and redeploys. Nothing tracks which key is exhausted, and nothing retries on the next one.
NyaProxy targets that gap. The README describes it as a gateway that sits between your applications and upstream APIs: clients call NyaProxy with an internal proxy key, and NyaProxy forwards each request to the configured upstream with the correct upstream credentials. The intended user is a team that wants one place to manage access to external or internal APIs, including AI providers, image generation APIs, SaaS APIs, and private services. It is not a general reverse proxy. It assumes the upstream authenticates with an API key, a bearer token, or a custom request header, and it is built around that assumption.
How requests flow through NyaProxy
The data path is straightforward. A client sends a request to NyaProxy with the proxy key. NyaProxy matches it against the configured API entries, applies the path and method policy, then selects an upstream credential. Credentials are defined under variables.<name>, and the headers key controls how the chosen credential is attached to the outbound request. The client never sees the upstream key.
Selection is governed by load_balancing_strategy, which the README lists as round_robin, random, least_requests, fastest_response, and weighted. The weighted option reads key_weights. If a request fails with one of the status codes listed under retry, NyaProxy cools down the failing key and rotates to the next one. A separate key_blocking setting temporarily removes credentials that return configured upstream error statuses. Those two mechanisms look similar on paper and the distinction matters: retry is per-request behavior, while key_blocking changes which keys are eligible for future requests.
Two features sit outside the request path. The queue setting holds requests until configured quota becomes available, which is useful when you would rather wait than receive a 429. The server.proxy setting sends upstream traffic through an HTTP or SOCKS proxy, for networks where outbound access is restricted.
Getting it running: pip, Docker, and the loopback default
The fastest path is pip install nya-proxy followed by nyaproxy. On first run the tool creates a starter config.yaml in the current directory and listens on 127.0.0.1:8080. The README flags a detail that is easy to miss: the starter config has no server.api_key, so authentication is disabled. That is safe only while bound to loopback. Set server.api_key before using --host 0.0.0.0.
Running with your own file is nyaproxy --config config.yaml. Config changes made through the /config UI, or to the file once it has been re-saved through the UI, trigger an automatic restart. Pass --no-reload to disable the file-watch supervisor. There is also --check-config, which validates schema and cross-field configuration and then exits. That flag is worth putting in CI, because a malformed YAML file otherwise surfaces as a failed restart rather than a clear error.
The Docker instructions carry a non-obvious constraint. Mount the directory, not config.yaml itself. Saving from the /config UI writes a temporary file and renames it over the target, and that rename fails with EBUSY against a bind-mounted file, so every save returns a 500. The mount must also be writable. The README notes that --user runs the container as you, since the image runs as uid 100 and could not otherwise write a directory you own, though Docker Desktop on macOS and Windows maps ownership automatically. The mounted directory holds config.yaml and .nya_state.json, which carries rate-limit windows and key cool-downs across restarts.
What the configuration surface actually covers
The README's feature table is the clearest map of the config. Credential injection uses headers and variables. Pooling uses variables.<name>. Rate limiting applies at four scopes: endpoint, upstream key, client IP, and proxy user. Request policy is enforced through allowed_paths and allowed_methods before forwarding. Body transformation uses request_body_substitution, which sets or removes JSON fields with conditional JMESPath rules. That last one is the most opinionated feature in the list, and it is also where you should be most careful. Rewriting request bodies in a gateway means the gateway now understands the payload shape of every upstream it fronts, and a JMESPath rule that was correct for one provider can silently corrupt a request to another.
Observability comes from a web dashboard plus a Prometheus /metrics endpoint, both gated by the dashboard setting. The README points to three built-in routes: /config for a configuration UI with validation, /dashboard for metrics, request history, and queue status, and /info for the configured API list and service status.
The CLI also supports a remote mode. --remote-url, --remote-api-key, and --remote-app-name pull configuration from a remote config server instead of a local file, and the README states this disables the local /config UI. That is a reasonable split: one team owns the config server, and the instances do not accept local edits. Bind address and port can come from flags or from the SERVER_HOST and SERVER_PORT environment variables.
Where the design will bite you
The restart-on-config-change behavior is the first real limitation. The README says config changes through the UI trigger an automatic restart so they take effect immediately, and that --no-reload exists for production setups where restarts should be explicit. Either way, applying a config change means restarting the process. In-flight requests during that window are not described in the material, so treat the restart as a real availability event and plan for it rather than assuming graceful draining.
The second limitation is scope. NyaProxy rate-limits by endpoint, upstream key, client IP, and proxy user. That covers abuse control and quota protection, but it is not the same as per-tenant accounting. If you need to bill individual end users, enforce per-organization token budgets, or produce per-customer usage reports, the four scopes here will not map cleanly onto that model. You would be building the accounting layer elsewhere.
The third is the authentication default. Authentication is disabled until server.api_key is set. The README is explicit that this is safe only while bound to loopback and that the port should not be published until the key is set. That is a reasonable default for a local tool, and a sharp edge for anyone who copies the Docker command without reading the warning.
Finally, the README includes a usage constraint that is easy to skim past: use NyaProxy only with credentials and traffic patterns that are allowed by the upstream service terms. Rotating across a pool of keys to work around a provider's per-key quota may violate those terms depending on the provider. The project states the constraint; it does not enforce it.
Alternatives and the difference in approach
The obvious comparison is a general-purpose reverse proxy such as nginx or Envoy. Those handle TLS termination, HTTP/2, connection pooling, and mature access logging, and they can inject a static header via configuration. What they do not do out of the box is hold a pool of credentials for one upstream and choose among them per request based on least_requests or fastest_response, with cool-down of keys that return specific error statuses. That rotation logic is the core of NyaProxy, and it is the part you would otherwise write yourself.
The other comparison is provider SDKs with built-in retry and key rotation, which several AI vendors ship. Those keep you inside one vendor's client and one vendor's API shape. NyaProxy's claim is breadth: the README frames it as working with any HTTP API that uses keys or tokens, which means one gateway for OpenAI, Gemini, Anthropic, an image generator, and an internal service. The trade-off is that a generic gateway cannot know provider-specific semantics. It can retry a 429 and rotate a key, but it will not understand that a particular provider's streaming response needs different timeout handling, or that a given endpoint has a different quota model than the rest of the API. If your needs are deep and single-vendor, the SDK is the better fit. If they are shallow and multi-vendor, the gateway removes duplicated plumbing.
Maintenance, licence, and what to verify first
NyaProxy is MIT-licensed, which permits commercial use and modification with minimal conditions. That is the most permissive common choice, and the practical implication is that you can vendor it or fork it without a licensing conversation. It also means there is no warranty and no support obligation from the maintainers, so operational ownership sits with you. This is not legal advice; read the LICENSE file for the actual terms.
The release cadence visible in the supplied material is tight: v0.8.0, v0.8.1, and v0.8.2 all landed on 2026-07-20. Three patch and minor releases in a single day suggests active development, and it also suggests the config schema is still moving. The README notes that the YAML is validated against a bundled JSON schema, which helps, but a fast-moving schema means you should pin a version rather than track latest in production. The project is written in Python and published to PyPI as nya-proxy, so upgrades are a pip install away and rollbacks are equally cheap.
Before adopting, verify three things against your own setup. Run nyaproxy --check-config on your YAML so schema errors surface before a restart does. Confirm that allowed_paths and allowed_methods cover every endpoint your clients call, since the policy is applied before forwarding and a missing path is a hard block. And decide where .nya_state.json lives, because it carries rate-limit windows and key cool-downs across restarts and will be lost if the container's writable directory is ephemeral.
Editorial conclusion
Adopt NyaProxy if your application code is scattered with provider keys, you already run several keys per provider, and you want one binary to own rotation, rate limits, and retries. Do not adopt it if you need per-end-user quotas, a hardened public edge, or a proxy that does not restart on every config change. Before you commit, run nyaproxy --check-config against your YAML, set server.api_key, and confirm that the paths listed in allowed_paths cover every endpoint your clients call.
Community notes