Documents
Build request policies in Ruby inside nginx. These pages describe the
v3 development branch next: implemented behavior and planned work are
kept separate. For the released 2.7 line, use the stable documentation.
Try a working example
Section titled “Try a working example”- Model routing with local mocks: choose an upstream by model, verify credential replacement, then edit the Ruby mapping and send the same request again. No provider key is needed.
- Install: build the module for your own nginx, with the requirements, build options and upgrade checks.
Add a policy to your application
Section titled “Add a policy to your application”- Model API relay: client-key checks, model routing, concurrency limits and streamed relay. Each planned extension is marked.
- HTTP routing: select a backend from request data.
- Access control: refuse clients on a local denylist.
- Rate limits: apply a limit per API key.
- Response filters: modify a response body.
- TCP connections: check the client before relaying a connection.
- MCP gateway design: an unverified architecture, with its missing evidence and boundaries stated explicitly.
- Planned gateway and site access uses: MCP policy and client profiles, model API fallback, AI crawler requests, and cache/telemetry boundaries for v3.
- Glossary: the terms these pages use for models, model APIs, agents, MCP, A2A, their traffic and the AI gateway.
Look up an API or build option
Section titled “Look up an API or build option”- Directives: where nginx calls Ruby and how to configure it.
- Ruby classes and methods: the API available to handlers.
- Build reference: compile options and bundled gems.
Understand the request lifecycle
Section titled “Understand the request lifecycle”- Request phases: the order of handlers.
- Filters: headers, body chunks and their constraints.
- Waiting without blocking: yielding work to nginx.
- Lifetimes: request-owned and shared worker state.
Operate and upgrade
Section titled “Operate and upgrade”- Release notes: read behavior changes before upgrading.
- Migration from 2.x: changes required for v3.
- Trust boundary: what the module and each script must validate.
- Security policy: supported releases and private vulnerability reporting.
Contribute or follow development
Section titled “Contribute or follow development”- Contributing: scope, review and contribution steps.
- Testing: the test suites and how to run them.
- Development procedure: branch workflow and shared handoffs.
- Current work: the dated queue and public checkpoints.
- Branch strategy: maintenance and development lines.
- Other use cases: additional examples, with their context.
License
Section titled “License”ngx_mruby is distributed under the MIT License.