🦙 rama® (ラマ) is a modular service framework for the 🦀 Rust language.
The framework is intentionally explicit. Your network stack is built from services, layers, transports, protocols, and state that you compose yourself. That makes the shape of the system visible in the code, instead of hidden behind framework magic or configuration.
This makes Rama a good fit not only for proxies, but for network services where the stack itself matters: how traffic enters, how it is decoded, where state lives, what gets inspected, what gets transformed, and where it goes next.
Whether you're inspecting traffic for security analysis, writing a web service, emulating clients with custom user agents, controlling connection behavior for advanced testing, or building high-performance proxies, Rama provides a clean and composable Tokio-native foundation for network services in Rust.
Rama is used in production for network security, data extraction, API gateways, routing, and other networked systems. Commercial support and partner offerings are available at ramaproxy.com.
This framework is developed and maintained by Plabayo, a European software studio based in Gent, Belgium, focused on building resilient, interoperable, and secure digital infrastructure.
The book explains the ideas, the examples show working stacks, and the Rust docs are the API reference.
| If you want to... | Go here |
|---|---|
| Understand why Rama exists | Why Rama |
| Learn the core model | Intro to Rama |
| Run working code | Examples |
| Build a proxy | Intro to proxies and proxy examples |
| Operate advanced proxy stacks | Operate Proxies |
| Build an HTTP service | Web servers and HTTP service examples |
| Build an HTTP client | HTTP clients and http_high_level_client.rs |
| Use Rama from the terminal | rama CLI |
| Look up APIs | docs.rs or edge docs |
| Get commercial support | ramaproxy.com |
Rama is built for programmable network services: software that accepts, opens, inspects, transforms, routes, proxies, or generates network traffic.
| Area | Examples |
|---|---|
| Proxies | reverse proxies, HTTP(S) proxies, SOCKS5 proxies, SNI proxies, MITM proxies, transparent proxies, HAProxy PROXY protocol |
| HTTP services | routers, static files, APIs, health checks, WebSockets, SSE, gRPC, FastCGI |
| HTTP clients | high-level clients, pooled clients, proxy-aware clients, user-agent emulation, redirect and middleware stacks |
| TLS and identity | Rustls, BoringSSL, TLS termination, dynamic certificates, mTLS, ACME |
| Traffic inspection | protocol inspection, TLS and HTTP fingerprinting, HAR recording, curl export, diagnostics |
| Lower-level networking | TCP, UDP, Unix sockets, DNS, transport middleware, connection pooling |
| Platform integrations | Apple Network Extension, Apple XPC, Linux tproxy, Windows WFP |
For the full capability overview, see the website feature table and the API docs. All protocols implemented in rama are made with the entire range of clients, servers and proxies in mind.
For advanced proxy operation, see the Operate Proxies chapters. For Apple transparent proxying, see the Apple transparent proxy example.
- Services all the way down: Rama uses the same service model across clients, servers, middleware, and lower network layers.
- Explicit stacks: transports, TLS, protocols, state, and middleware are composed in code, so the path traffic takes stays visible.
- Transport-to-HTTP control: work at the HTTP layer when that is enough, or reach into TCP, UDP, TLS, DNS, and connection state when needed.
- Modular crates: use the top-level
ramacrate, or depend on smaller crates when you want a focused dependency graph. - Tower interop: Rama has its own service traits, with compatibility for Tower where that helps.
The examples directory
contains tested examples for common stacks.
| Goal | Example |
|---|---|
| Minimal HTTP service | http_service_hello.rs |
| HTTP router | http_web_router.rs |
| High-level HTTP client | http_high_level_client.rs |
| HTTP CONNECT proxy | http_connect_proxy.rs |
| SOCKS5 proxy | socks5_connect_proxy.rs |
| MITM proxy | http_mitm_proxy_boring.rs |
| Linux transparent proxy | linux_tproxy_tcp.rs |
| Apple transparent proxy | ffi/apple/examples/transparent_proxy |
| Tower integration | http_rama_tower.rs |
Most examples can be run with cargo and the required feature flags:
cargo run --example http_service_hello --features=http-full
cargo run --example http_connect_proxy --features=http-full
cargo run --example socks5_connect_proxy --features=dns,socks5Check each example's module documentation for exact usage and feature requirements.
The rama binary lets you use parts of Rama without writing Rust code. It can
act as an HTTP client, run local IP/echo/fingerprinting services, and run
configured proxy stacks.
Learn how to install and use it in the rama CLI chapter.
- MSRV: Rama requires Rust
1.96. - Platforms: Linux, macOS, and Windows are tier 1 platforms. Android and iOS targets are checked in CI.
- Safety: Rama avoids unsafe code where possible. Low-level protocol code and FFI-backed crates use unsafe where needed.
- Supply chain: dependencies are audited with
cargo vet. - Performance: Rama's default HTTP implementation is based on Hyper internals and is designed for production network services.
- Roadmap: planned work is tracked in GitHub milestones.
Most users can start with rama. The smaller
crates exist for users who want finer control over dependencies or extension
points.
See the ecosystem chapter for more context.
Rama crates in this repository:
rama: top-level craterama-error: error utilities for rama and its usersrama-macros: contains the procedural macros used byramarama-utils: utilities crate for ramarama-ws: WebSocket (WS) support for ramarama-core: core crate containing the service and layer traits used by all otherramacode, as well as some other core utilitiesrama-crypto: rama crypto primitives and dependenciesrama-net: rama network types and utilitiesrama-net-apple-networkextension: Apple Network Extension support for ramarama-net-apple-xpc: Apple XPC support for ramarama-dns: DNS support for ramarama-unix: Unix (domain) socket support for ramarama-tcp: TCP support for ramarama-udp: UDP support for ramarama-tls-acme: ACME support for ramarama-tls-boring: Boring TLS support for ramarama-tls-rustls: Rustls support for ramarama-proxy: proxy types and utilities for ramarama-socks5: SOCKS5 support for ramarama-fastcgi: FastCGI support for ramarama-haproxy: rama HAProxy supportrama-ua: User-Agent (UA) support forramarama-http-types: http types and utilitiesrama-http-headers: typed http headersrama-json: streaming JSON tokenizer, JSONPath selection, and rewriting utilitiesrama-grpc: gRPC support for ramarama-grpc-build: gRPC codegen support for ramarama-http: rama http services, layers and utilitiesrama-http-macros: proc-macros powering the type-safe HTML templating inrama-http::protocols::htmlrama-http-backend: default http backend forramarama-http-core: http protocol implementation drivingrama-http-backendrama-http-hyperium: conversions between rama and the hyperiumhttpcraterama-tower: tower compatibility forrama
Related Plabayo crates and projects:
rama-boring: BoringSSL bindings for ramarama-boring-sys: FFI bindings to BoringSSL for ramarama-boring-tokio: Tokio SSL streams backed by BoringSSLrama-boringssl: BoringSSL fork used byrama-boringtokio-graceful: graceful shutdown utilities for Tokiovenndb: set and relation matching utilities used by Rama proxy componentshomebrew-rama: Homebrew formula for theramaCLI
Questions, ideas, and project discussion are welcome on Discord. Bug reports and feature requests can be opened as GitHub issues.
Rama also has a public channel on the official Discord of the Tokio project: https://discord.com/channels/500028886025895936/1349098858831024209.
Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.
Good places to start:
Some issues have a needs input
label. These usually need discussion, research, or design work before
implementation starts.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in rama by you shall be licensed as both MIT
and Apache-2.0,
without any additional terms or conditions.
Rama is licensed under either of:
Rama is free and open-source software. Sponsorships help fund development, infrastructure, testing, and maintenance.
Commercial support, consulting, training, and custom development are available through ramaproxy.com. More background is available in the Sponsor chapter.
If Rama is not the right fit for your proxy work, you may also want to look at
pingora by Cloudflare and
g3proxy by ByteDance.
The Why Rama chapter explains how Rama fits between off-the-shelf proxies and building a stack from scratch.
Available at https://ramaproxy.org/book/faq.html.
Tip
📚 If you like Rama, you might also like Netstack.FM®, a podcast about networking, Rust, and everything in between.
