# Arion

> Arion is an open-source Envoy-compatible proxy and AI gateway: an L7/L4 proxy and API gateway, an MCP gateway for serving tools to agents, and a programmable data plane, written in Rust.

- [Home](/index.md): Product overview, extension paths and deployment choices.
- [Docs](/docs/index.md): Concepts and feature documentation.
- [Guides](/guides/index.md): Step-by-step configurations to run and verify.
- [Reference](/reference/index.md): Configuration, filters, xDS, SDK and observability lookup.
- [Builder](/builder/index.md): Compose an Arion configuration from vetted features.
- [Blog](/blog/index.md): Project releases, internals and performance engineering.
- [GitHub](https://github.com/arion-gateway/arion): Source code and issue tracker.

## Docs

- [Get started: What is Arion](/docs/get-started/what-is-arion/index.md): An Envoy-compatible L7/L4 proxy and API gateway in Rust, with an MCP gateway for serving tools to agents and a programmable data plane.
- [Get started: How Arion works](/docs/get-started/how-it-works/index.md): One picture of the data plane: listeners accept connections, filter chains process them, routes pick clusters, clusters hold endpoints.
- [Get started: Install](/docs/get-started/install/index.md): Build the arion binary from source, pick optional Cargo features, build the Docker image, or run it on Kubernetes.
- [Get started: Quickstart](/docs/get-started/quickstart/index.md): Run an echo upstream, write a thirty-line arion.yaml, start Arion and proxy your first request — about five minutes end to end.
- [Concepts: Architecture](/docs/concepts/architecture/index.md): How the Arion process is organized: a services runtime for control work, proxy runtimes for the data path, and channels between them.
- [Concepts: Life of a request](/docs/concepts/life-of-a-request/index.md): The path a connection and its requests take through Arion, from accept to upstream and back, and where each filter runs.
- [Concepts: The filter chain](/docs/concepts/filter-chain/index.md): The three levels filters attach at, the ordering rules Arion enforces, and how routes override or disable individual HTTP filters.
- [Concepts: The configuration model](/docs/concepts/configuration-model/index.md): The Arion file's top-level keys, how flags and environment variables override them, and how static and dynamic resources fit together.
- [Concepts: Runtime and threading](/docs/concepts/runtime-and-threading/index.md): One multi-threaded runtime or one runtime per core: the runtime block, CPU detection, core pinning, and what SO_REUSEPORT changes.
- [Concepts: Envoy compatibility](/docs/concepts/envoy-compatibility/index.md): The promise Arion makes about Envoy configs: accepted means Envoy-like behavior; anything it cannot honor is refused, never ignored.
- [Traffic: Listeners](/docs/traffic/listeners/index.md): Bind socket addresses, choose a filter chain per connection, terminate TLS, and run listener filters such as the TLS inspector.
- [Traffic: Routing](/docs/traffic/routing/index.md): Match HTTP requests by host, path, headers and query, then forward, split, redirect, rewrite or answer them directly.
- [Traffic: Upstreams and load balancing](/docs/traffic/upstreams-and-load-balancing/index.md): Define clusters of upstream endpoints, choose how they are discovered, and pick a load-balancing policy with weights and priorities.
- [Traffic: Health checks and resilience](/docs/traffic/health-checks-and-resilience/index.md): Detect bad endpoints with active health checks, stop cascading failure with circuit breakers, and retry what is safe.
- [Traffic: Rate limiting](/docs/traffic/rate-limiting/index.md): Choose the right limiter: listener accept limits, connection caps, an external rate limit service, per-route token buckets, or per-user limits.
- [Traffic: TCP proxy](/docs/traffic/tcp-proxy/index.md): Forward raw TCP streams to a cluster, split them across weighted clusters, and route by TLS SNI without terminating TLS.
- [Security: TLS and mTLS](/docs/security/tls-and-mtls/index.md): Terminate TLS on listeners, require client certificates, originate TLS to upstreams, and select certificate chains by SNI.
- [Security: Secrets and rotation](/docs/security/secrets-and-rotation/index.md): Name TLS certificates and CAs as secrets, reference them from listeners and clusters, and rotate them over xDS without a restart.
- [Security: JWT authentication](/docs/security/jwt/index.md): Validate JSON Web Tokens against local or remote JWKS, choose which routes require which provider, and forward claims to backends.
- [Security: Authorization](/docs/security/authorization/index.md): Choose between RBAC rules, Cedar policies, and your own ext_proc or WASM extension for deciding what a caller may do.
- [Security: RBAC](/docs/security/rbac/index.md): Declarative allow/deny policies on connections (network RBAC) and requests (HTTP RBAC), with per-route overrides.
- [Security: Cedar policies](/docs/security/cedar-policies/index.md): Authorize HTTP requests with Cedar policy text evaluated in-process against the caller's JWT and the request's method, path and query.
- [Security: CORS](/docs/security/cors/index.md): Answer browser preflights at the gateway and control which web origins may call your API.
- [LLM Gateway: LLM gateway overview](/docs/llm-gateway/overview/index.md): What the LLM gateway does: one endpoint for several model providers, with failover, token budgets and guardrails. Documentation under construction.
- [AI Inference Gateway: AI inference gateway overview](/docs/ai-inference-gateway/overview/index.md): How Kubernetes Gateway API, InferencePool, and an endpoint picker (EPP) route inference requests through Arion to ready model server Pods.
- [MCP Gateway: MCP gateway overview](/docs/mcp-gateway/overview/index.md): How the MCP gateway filter turns Arion into an MCP server: one endpoint, a registry of namespaced tools, and two ways for agents to use them.
- [MCP Gateway: Tools mode](/docs/mcp-gateway/tools-mode/index.md): Conventional MCP serving: agents list and call tools one at a time, discover a large catalog through tool_search, and call anything they may use by name.
- [MCP Gateway: Code mode](/docs/mcp-gateway/code-mode/index.md): Serve one execute tool: the agent sends TypeScript that finds, calls and combines tools, and Arion runs it in a sandbox and returns one result.
- [MCP Gateway: Tools and REST backends](/docs/mcp-gateway/tools-and-rest-backends/index.md): Declare static MCP tools and map tools/call onto HTTP requests: namespaces, path templates, query parameters, body mapping and response handling.
- [MCP Gateway: OpenAPI tools](/docs/mcp-gateway/openapi-tools/index.md): Expand an OpenAPI 3.x document into one REST-backed MCP tool per operation, with operation filters, one shared policy and live updates over TDS.
- [MCP Gateway: Federating MCP servers](/docs/mcp-gateway/federation/index.md): Put Arion in front of upstream MCP servers: auto-discover their tools under a namespace, and control disclosure, caching and refresh.
- [MCP Gateway: Tool search](/docs/mcp-gateway/tool-search/index.md): Progressive tool disclosure for agents: eager and progressive tools, the tool_search tool, BM25 and remote-embedding ranking, and the search endpoint.
- [MCP Gateway: Tool authorization](/docs/mcp-gateway/tool-authorization/index.md): Per-tool RBAC for MCP: allow or deny listing, search, calls and code-mode scripts based on validated JWT claims and header fields.
- [MCP Gateway: Tool discovery over xDS (TDS)](/docs/mcp-gateway/tool-discovery-tds/index.md): Deliver MCP tools, OpenAPI sources, dynamic servers and code-mode toolkits from a control plane: scopes, resource types, and update and remove rules.
- [Extend: Extending Arion](/docs/extend/overview/index.md): Choose between a WASM filter, an external processing service, or a native Rust filter to run your own logic in the request path.
- [Extend: WASM filters](/docs/extend/wasm-filters/index.md): Load a WebAssembly module into the HTTP filter chain: the wasm build feature, the filter config, plugin configuration, and instance lifecycle.
- [Extend: Rust SDK](/docs/extend/rust-sdk/index.md): Write a WASM filter in Rust: the arion_plugin entry point, lifecycle hooks, typestate handles, and building the module.
- [Extend: Callouts and shared state](/docs/extend/callouts-and-shared-state/index.md): Async HTTP and gRPC callouts, timers, and host-backed shared memory for WASM filters: atomics and versioned compare-and-swap blobs.
- [Extend: External processing](/docs/extend/ext-proc/index.md): Stream requests and responses to a gRPC service you run: processing modes, mutations, timeouts, failure mode, and per-route overrides.
- [Extend: Native HTTP filters](/docs/extend/http-filters-in-rust/index.md): How a native filter is wired into the Arion binary: the config enum, the type URL registry, the runtime dispatch, and per-route overrides.
- [Observe: Access logs](/docs/observe/access-logs/index.md): Record every request and connection Arion handles, with Envoy-compatible format strings, file/stdout/stderr sinks and rotation.
- [Observe: Logging](/docs/observe/logging/index.md): Configure Arion's application log: levels and per-module filters, stdout or rolling files, and timestamp timezone.
- [Observe: Metrics](/docs/observe/metrics/index.md): Envoy-style statistics for listeners, clusters and HTTP traffic, scraped by Prometheus or pushed over OpenTelemetry.
- [Observe: Tracing](/docs/observe/tracing/index.md): Distributed tracing with OpenTelemetry: OTLP export, sampling controls, and W3C, B3 and Jaeger propagation.
- [Observe: Admin interface](/docs/observe/admin-interface/index.md): A local HTTP endpoint for operating Arion: readiness, server info, listeners, clusters, certificates, stats and config dump.
- [Operate: Deploy](/docs/operate/deploy/index.md): Run Arion in production: a systemd unit, the Docker image, Kubernetes manifests, and sizing the runtime under CPU limits.
- [Operate: xDS control planes](/docs/operate/xds-control-planes/index.md): Connect Arion to an xDS control plane over delta ADS and update listeners, routes, clusters, endpoints and secrets at runtime.
- [Operate: Performance tuning](/docs/operate/performance-tuning/index.md): The runtime knobs: worker threads, one runtime versus per-core runtimes, CPU affinity, the jemalloc build and socket basics.
- [Operate: Troubleshooting](/docs/operate/troubleshooting/index.md): Symptom-led fixes: startup refusals, certificate and SNI errors, listener and upstream failures, JWT 401s and missing endpoints.

## Guides

- [Proxy: Build an L7 load balancer](/guides/proxy/l7-load-balancer/index.md): Stand up an HTTP load balancer that spreads traffic across three upstreams, health-checks them, retries failures and logs every request.
- [Proxy: Build an API gateway](/guides/proxy/api-gateway/index.md): Put a rate limit and JWT authentication in front of an API, with retries and health checking on the upstream cluster.
- [Proxy: Canary with weighted clusters](/guides/proxy/canary-with-weighted-clusters/index.md): Send 90% of traffic to a stable cluster and 10% to a canary, watch the split, and shift or roll back by editing two numbers.
- [Proxy: Route TCP at L4](/guides/proxy/route-tcp-at-l4/index.md): Front a TCP service with Arion: PROXY protocol from the edge, a connection cap, a source-IP allowlist and a health-checked upstream pair.
- [Proxy: Migrate from Envoy](/guides/proxy/migrate-from-envoy/index.md): Run an existing Envoy bootstrap under Arion, read the refusals it produces, and reconnect to your xDS control plane.
- [AI inference: Inference routing](/guides/inference/inference-routing/index.md): Configure Kubernetes Gateway API and InferencePool resources so Arion routes requests to ready model server Pods chosen by an external endpoint picker.
- [MCP: Build an MCP gateway](/guides/mcp/mcp-gateway/index.md): Expose REST backends as MCP tools behind one authenticated endpoint, with per-tool access control from JWT claims.
- [MCP: Code mode for agents](/guides/mcp/code-mode-for-agents/index.md): Serve REST tools to agents through one execute tool: the agent sends a TypeScript script, and Arion runs the whole workflow in a sandbox.
- [Extend: Your first Wasm filter](/guides/extend/first-wasm-filter/index.md): Write a WebAssembly HTTP filter with the Arion Wasm SDK, build it, and run it in the request path of a listener.

## Reference

- [Configuration: File format](/reference/configuration/file-format/index.md): Every top-level key of the Arion configuration file: runtime, logging, access_logging, metrics, timezone and the bootstrap forms.
- [Configuration: Command line](/reference/configuration/cli/index.md): Every flag of the arion binary: config file selection, Envoy bootstrap override and runtime tuning.
- [Configuration: Environment variables](/reference/configuration/environment-variables/index.md): The environment variables the arion binary reads: runtime sizing, log filtering and config-referenced secrets.
- [Configuration: Native bootstrap](/reference/configuration/native-bootstrap/index.md): The bootstrap: key — Arion's native resource form, its top-level keys, and how it relates to envoy_bootstrap.
- [Resources: Listeners](/reference/resources/listeners/index.md): Field reference for listeners, filter chains, filter chain matching and the downstream TLS context.
- [Resources: Routes](/reference/resources/routes/index.md): Field reference for route configurations: virtual hosts, route matching, actions, retry policies and header mutations.
- [Resources: Clusters](/reference/resources/clusters/index.md): Field reference for clusters: discovery types, load balancing, endpoints, health checks, circuit breakers, protocol options and upstream TLS.
- [Resources: Secrets](/reference/resources/secrets/index.md): Field reference for TLS certificate and validation-context secrets, data sources and SDS name references.
- [Filters · Listener filters: TLS inspector](/reference/filters/listener/tls-inspector/index.md): Listener filter that reads the SNI from the TLS ClientHello so filter chains can match on server name.
- [Filters · Listener filters: Proxy protocol](/reference/filters/listener/proxy-protocol/index.md): Listener filter that reads a PROXY protocol v1/v2 header and restores the original client address.
- [Filters · Listener filters: Local rate limit](/reference/filters/listener/local-rate-limit/index.md): Listener filter that caps the rate of accepted connections with a token bucket.
- [Filters · Network filters: HTTP connection manager](/reference/filters/network/http-connection-manager/index.md): Terminal network filter that speaks HTTP, runs the HTTP filter chain and routes requests to clusters.
- [Filters · Network filters: TCP proxy](/reference/filters/network/tcp-proxy/index.md): Terminal network filter that forwards the raw byte stream to an upstream cluster.
- [Filters · Network filters: RBAC](/reference/filters/network/rbac/index.md): Network filter that allows or denies connections by client address, destination and SNI.
- [Filters · Network filters: Rate limit](/reference/filters/network/rate-limit/index.md): Network filter that checks each new connection against an external gRPC rate limit service.
- [Filters · Network filters: Connection limit](/reference/filters/network/connection-limit/index.md): Network filter that caps the number of concurrently active connections on a filter chain.
- [Filters · HTTP filters: Router](/reference/filters/http/router/index.md): The mandatory terminal HTTP filter that executes the routing decision and sends the request upstream.
- [Filters · HTTP filters: CORS](/reference/filters/http/cors/index.md): HTTP filter that answers preflight requests and stamps CORS headers on responses.
- [Filters · HTTP filters: Local rate limit](/reference/filters/http/local-rate-limit/index.md): HTTP filter that rate-limits requests with an in-process token bucket, overridable per route.
- [Filters · HTTP filters: User rate limit](/reference/filters/http/user-rate-limit/index.md): Arion HTTP filter that keeps a separate rate limit bucket per caller, identified by a header.
- [Filters · HTTP filters: JWT authentication](/reference/filters/http/jwt-authn/index.md): HTTP filter that validates JSON Web Tokens against configured providers and JWKS keys.
- [Filters · HTTP filters: RBAC](/reference/filters/http/rbac/index.md): HTTP filter that allows or denies requests by header-based policies, overridable per route.
- [Filters · HTTP filters: Cedar policy](/reference/filters/http/cedar-policy/index.md): Arion HTTP filter that authorizes requests with Cedar policies over JWT claims and request context.
- [Filters · HTTP filters: External processing](/reference/filters/http/ext-proc/index.md): HTTP filter that streams headers and bodies to an external gRPC processor, overridable per route.
- [Filters · HTTP filters: Wasm](/reference/filters/http/wasm/index.md): HTTP filter that runs a WebAssembly module in-process on every request and response.
- [Filters · HTTP filters: MCP gateway](/reference/filters/http/mcp-gateway/index.md): Arion HTTP filter that serves a Model Context Protocol endpoint, maps tools onto REST, OpenAPI and MCP upstreams, and runs agent scripts in code mode.
- [xDS: Resource types](/reference/xds/resource-types/index.md): The xDS resource types Arion accepts from a control plane, the delta ADS transport, and the bootstrap keys that enable each.
- [xDS: TDS resources](/reference/xds/tds-resources/index.md): Tool Discovery Service: the xDS extension resources that add, update and remove MCP tools, OpenAPI sources, dynamic servers and toolkits at runtime.
- [SDK: Code mode SDK and limits](/reference/sdk/code-mode-sdk-and-limits/index.md): What a code mode script can call, the catalog operations and their results, call envelopes and error codes, the execute result, and every limit.
- [Observability: Access log operators](/reference/observability/access-log-operators/index.md): The complete table of command operators accepted in Arion access-log and header format strings.
- [Observability: Metrics list](/reference/observability/metrics-list/index.md): Every metric Arion emits, by family, with types and labels, and where to scrape them.
- [Observability: Admin API](/reference/observability/admin-api/index.md): The admin listener's endpoints: readiness, server info, listeners, clusters, certificates, memory, config dump, stats and counter reset.
- [Envoy compatibility: Supported configuration](/reference/envoy-compatibility/supported-configuration/index.md): The full matrix of Envoy configuration Arion accepts: bootstrap, listeners, filters, routing, clusters and TLS, with what is refused.

## Optional

- [FAQ](/faq/index.md): Short answers linking to each topic's home page.
- [Community](/community/index.md): Where the community talks and how to contribute.
- [Security policy](/security/index.md): How to report a vulnerability.
- [Support](/support/index.md): Where to get help.