rama banner

Crates.io Docs.rs MIT License Apache 2.0 License Build Status

🦙 Rama (ラマ) is a modular service framework for the 🦀 Rust language to move and transform your network packets.

🎧 New! Listen to Netstack.FM Episode 1 — the podcast about rethinking networking with Rust and building with Rama.

This framework is designed for developers who need fine-grained, programmable control over how packets are handled across the network stack. Whether you're intercepting traffic for security analysis, emulating clients with custom user agents, hijacking connections for advanced testing, or building high-performance proxies, Rama provides a clean and composable Rust-native foundation.

With support for modular packet pipelines, deep protocol introspection, and advanced socket manipulation—including features like transparent proxying and HAProxy protocol support—Rama makes it easy to prototype, deploy, and scale complex network behavior with safety and speed.

It's not just a toolkit—it's a mindset shift for how to design and operate dynamic, programmable network services.

💡 The motivations behind Rama's creation are detailed in the "Why Rama" chapter.

Rama is async-first using Tokio as its only Async Runtime. Please refer to the examples found in the /examples dir to get inspired on how you can use it for your purposes.

While powerful and flexible, Rama might not be the ideal framework for everyone. If you're building a conventional web server or need a simple HTTP client, other crates might better suit your needs. Although we at Plabayo use Rama extensively for our web infrastructure (clients, servers, and proxies), it has a steeper learning curve and a smaller community compared to more established alternatives.

Consider these alternatives for simpler use cases:

  • Axum for building standard HTTP web servers. It offers extensive community support and ecosystem integrations. However, be aware that Axum's higher-level abstractions may limit your control over the web stack when you need to implement non-standard features.

  • Reqwest for basic HTTP client needs. It's ideal when you don't require fine-grained control over HTTP requests/responses or TLS configuration details.

If you're specifically building proxies and find Rama's approach doesn't align with your needs, explore the alternatives listed in our project README.

Rama's core philosophy centers on empowerment and modularity. It provides a foundation for building proxies, servers, and clients without imposing restrictions. Any component in a Rama-based web stack can be customized to meet your specific requirements, even if that means implementing custom solutions for particular layers.

We gratefully acknowledge that Rama stands on the shoulders of giants. For more details about our inspirations and dependencies, see our acknowledgements.

In some cases, we've had to fork external crates to accommodate our specific needs or scope requirements. While this creates additional maintenance work, we believe it's worthwhile to support our mission of empowering Rama users. Details about these forks can be found in our FORK.md. We maintain the original code structure in these forks to facilitate upstream synchronization and contribute patches back when possible.

💡 If your organization relies on Rama (ラマ) for its operations, we invite you to consider becoming a sponsor 💖. By supporting our project, you'll help ensure its continued development and success. To learn more about sponsorship opportunities, please refer to the "Sponsors" chapter in this book or contact us directly at sponsor@ramaproxy.org.

Rama comes with 🔋 batteries included, giving you the full freedom to build the middleware and services you want, without having to repeat the "common":

categorysupport list
✅ transports✅ tcp ⸱ ✅ udp ⸱ ✅ Unix (UDS) ⸱ ✅ middleware
✅ http✅ auto ⸱ ✅ http/1.1 ⸱ ✅ h2 ⸱ 🏗️ h3 (2) ⸱ ✅ middleware
✅ web server✅ fs ⸱ ✅ redirect ⸱ ✅ router ⸱ ✅ dyn router ⸱ ✅ static router ⸱ ✅ handler extractors ⸱ ✅ k8s healthcheck
✅ http client✅ easy client ⸱ ✅ high level API ⸱ ✅ BoringSSL Connect ⸱ ✅ Rustls Connect ⸱ ✅ HTTP Proxy Connect ⸱ ✅ Socks5 Proxy Connect ⸱ ❌ Chromium Http (3)
✅ tls✅ Rustls ⸱ ✅ BoringSSL ⸱ ❌ NSS (3)
✅ dns✅ DNS Resolver
✅ proxy protocols✅ PROXY protocol ⸱ ✅ http proxy ⸱ ✅ https proxy ⸱ ✅ socks5(h) proxy
✅ web protocols✅ SSE ⸱ ✅ WS ⸱ ❌ Web Transport (3) ⸱ ❌ gRPC (2)
✅ async-method trait services✅ Service ⸱ ✅ Layer ⸱ ✅ context ⸱ ✅ dyn dispatch ⸱ ✅ middleware
✅ telemetry✅ tracing ⸱ ✅ opentelemetry ⸱ ✅ http metrics ⸱ ✅ transport metrics
✅ upstream proxies✅ MemoryProxyDB ⸱ ✅ Username Config ⸱ ✅ Proxy Filters
✅ User Agent (UA)✅ Http Emulation ⸱ ✅ Tls Emulation ⸱ ✅ UA Parsing
✅ Fingerprinting✅ Ja3 ⸱ ✅ Ja4 ⸱ ✅ Ja4H ⸱ 🏗️ Akamai passive h2 (1) ⸱ ✅ Peetprint (tls)
✅ utilities✅ error handling ⸱ ✅ graceful shutdown ⸱ ✅ Connection Pooling ⸱ ✅ Tower Adapter ⸱ 🏗️ IP2Loc (1)
🏗️ Graphical Interface🏗️ traffic logger (2) ⸱ 🏗️ curl export (1) ⸱ 🏗️ TUI implementation (2) ⸱ ❌ traffic intercept (3) ⸱ ❌ traffic replay (3)
✅ binary✅ prebuilt binaries ⸱ 🏗️ proxy config (2) ⸱ ✅ http client ⸱ ❌ WASM Plugins (3)
🏗️ data scraping🏗️ Html Processor (2) ⸱ ❌ Json Processor (3)
❌ browser❌ JS Engine (3) ⸱ ❌ Web API Emulation (3)

🗒️ Footnotes

The primary focus of Rama is to aid you in your development of proxies:

The Distortion proxies support comes with User Agent (UA) emulation capabilities. The emulations are made possible by patterns and data extracted using rama-fp. The service is publicly exposed at https://fp.ramaproxy.org, made possible by our sponsor host https://fly.io/.

🔁 https://echo.ramaproxy.org/ is another service publicly exposed. In contrast to the Fingerprinting Service it is aimed at developers and allows you to send any http request you wish in order to get an insight on the Tls Info and Http Request Info the server receives from you when making that request.

curl -XPOST 'https://echo.ramaproxy.org/foo?bar=baz' \
  -H 'x-magic: 42' --data 'whatever forever'

Feel free to make use of while crafting distorted http requests, but please do so with moderation. In case you have ideas on how to improve the service, please let us know by opening an issue.

BrowserStack sponsors Rama by providing automated cross-platform browser testing on real devices, which uses the public fingerprinting service to aid in automated fingerprint collection on both the Http and Tls layers. By design we do not consider Tcp and Udp fingerprinting.

Next to proxies, Rama can also be used to develop Web Services and Http Clients.

GitHub Sponsors Buy Me A Coffee Paypal Donation Discord

Rama also has a channel on the official Discord of the Tokio project. Feel free to join us there as well: https://discord.com/channels/500028886025895936/1349098858831024209

Please consult the official docs.rs documentation or explore the examples found in the /examples dir to know how to use rama for your purposes.

💡 You can find the edge docs of the rama framework code at https://ramaproxy.org/docs/rama/index.html, which contains the documentation for the main branch of the project.

🤝 Enterprise support, software customisations, integrations, professional support, consultancy and training are available upon request by sending an email to partner@ramaproxy.org. Or get an entireprise subscription via Gihub Sponsors.

💖 Please consider becoming a sponsor if you critically depend upon Rama (ラマ) or if you are a fan of the project.

⌨️ | rama binary

The rama binary allows you to use a lot of what rama has to offer without having to code yourself. It comes with a working http client for CLI, which emulates User-Agents and has other utilities. And it also comes with IP/Echo services.

It also allows you to run a rama proxy, configured to your needs.

Learn more about the rama binary and how to install it at /deploy/rama-cli.md.

🧪 | Experimental

🦙 Rama (ラマ) is to be considered experimental software for the foreseeable future. In the meanwhile it is already used in production by ourselves and others alike. This is great as it gives us new perspectives and data to further improve and grow the framework. It does mean however that there are still several non-backward compatible releases that will follow 0.2.

In the meanwhile the async ecosystem of Rust is also maturing, and edition 2024 is also to be expected as a 2024 end of year gift. It goes also without saying that we do not nilly-willy change designs or break on purpose. The core design is by now also well defined. But truth has to be said, there is still plenty to be improve and work out. Production use and feedback from you and other users helps a lot with that. As such, if you use Rama do let us know feedback over Discord, email or a GitHub issue.

👉 If you are a company or enterprise that makes use of Rama, or even an individual user that makes use of Rama for commcercial purposes. Please consider becoming a business/enterprise subscriber. It helps make the development cycle to remain sustainable, and is beneficial to you as well. As part of your benefits we are also available to assist you with migrations between breaking releases. For enterprise users we can even make time to develop those PR's in your integration codebases ourselves on your behalf. A win for everybody. 💪