plabayo/rama

modular service framework to move and transform network packets

1,199

stars

2,257

commits

Rust

primary language

Sep 11, 2026

updated

ramaproxy.org

http

https

mitm

network

networking

network-programming

proxy

rust

scraping

tls

Browse cluster: HTTP/2 and WebSocket Server Implementations →

README

🦙 rama® (ラマ) is a modular service framework for the 🦀 Rust language that provides a cohesive foundation for building network clients, servers, proxies, and combinations thereof.

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.

rama — modular service framework to move and transform network packets

Start here

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

What can you build?

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, Proxy Auto-Configuration (PAC)
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
Content adaptation	ICAP clients, servers, HTTP adaptation layers, and Preview support
Runtime boundaries	async services, blocking service adapters, blocking HTTP(S) and WebSocket clients
TLS and identity	Rustls, BoringSSL, TLS termination, dynamic certificates, mTLS, ACME
Traffic inspection	protocol inspection, TLS and HTTP fingerprinting, HAR recording, curl export, diagnostics
Embedded scripting	JavaScript runtime, PAC evaluation and generation
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.

Core ideas

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 by design: use the top-level rama crate and compose only the protocol and runtime building blocks you need for an application, library, or framework, with your own services and layers where desired.
Tower interop: Rama has its own service traits, with compatibility for Tower where that helps.
Blocking boundaries: expose async stacks to synchronous code through BlockingService and rt::blocking, without making the stack itself synchronous.

Examples

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`
HTTP(S) proxy with ICAP	`http_icap_proxy.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 -p rama-examples --bin http_service_hello --features=http-full
cargo run -p rama-examples --bin http_connect_proxy --features=http-full
cargo run -p rama-examples --bin socks5_connect_proxy --features=dns,socks5

Check each example's module documentation for exact usage and feature requirements.

`rama` binary

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.

Status

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.

All rama and other crates developed by Plabayo

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 crate
rama-error: error utilities for rama and its users
rama-macros: contains the procedural macros used by rama
rama-utils: utilities crate for rama
rama-ws: WebSocket (WS) support for rama
rama-core: core crate containing the service and layer traits used by all other rama code, as well as some other core utilities
rama-crypto: rama crypto primitives and dependencies
rama-net: rama network types and utilities
rama-net-apple-networkextension: Apple Network Extension support for rama
rama-net-apple-xpc: Apple XPC support for rama
rama-dns: DNS support for rama
rama-unix: Unix (domain) socket support for rama
rama-tcp: TCP support for rama
rama-udp: UDP support for rama
rama-tls-acme: ACME support for rama
rama-tls-boring: Boring TLS support for rama
rama-tls-rustls: Rustls support for rama
rama-proxy: proxy types and utilities for rama
rama-socks5: SOCKS5 support for rama
rama-fastcgi: FastCGI support for rama
rama-haproxy: rama HAProxy support
rama-icap: ICAP support for rama
rama-ua: User-Agent (UA) support for rama
rama-http-types: http types and utilities
rama-http-headers: typed http headers
rama-json: streaming JSON tokenizer, JSONPath selection, and rewriting utilities
rama-js: embedded javascript execution
rama-pac: proxy auto-configuration (PAC) support
rama-grpc: gRPC support for rama
rama-grpc-build: gRPC codegen support for rama
rama-grpc-macros: proc-macros to define gRPC services inline, without a .proto file
rama-http: rama http services, layers and utilities
rama-http-macros: proc-macros powering the type-safe HTML templating in rama-http::protocols::html
rama-http-backend: default http backend for rama
rama-http-core: http protocol implementation driving rama-http-backend
rama-http-hyperium: conversions between rama and the hyperium http crate
rama-tower: tower compatibility for rama
rama-ttrpc: ttRPC (gRPC for low-memory environments) support for rama
rama-ttrpc-build: ttRPC codegen support for rama

Related Plabayo crates and projects:

rama-boring: BoringSSL bindings for rama
rama-boring-sys: FFI bindings to BoringSSL for rama
rama-boring-tokio: Tokio SSL streams backed by BoringSSL
rama-boringssl: BoringSSL fork used by rama-boring
tokio-graceful: graceful shutdown utilities for Tokio
venndb: set and relation matching utilities used by Rama proxy components
homebrew-rama: Homebrew formula for the rama CLI

Community

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.

Contributing

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.

License

Rama is licensed under either of:

Sponsors and support

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.