Skip to content

About

A cross-platform high performing HTTP(S) proxy server in C#.

Topics

Resources

Contributing

Security policy

Stars

2.0k stars

Watchers

4 watching

Forks

Repository files navigation

Titanium Web Proxy

Embeddable .NET 10 HTTP(S) and MITM library, standalone CLI and Kubernetes reverse proxy, and desktop MITM debugger — on Windows, Linux, and macOS.

Website · Download · Quick Start · Benchmarks · Docs · License

Requires .NET 10 or later for the library. CLI and Inspector downloads are self-contained (no SDK needed to run them).

Build NuGet NuGet downloads

Major features

Pillar What you get Start here
Embeddable .NET HTTP(S) & MITM (Titanium.Web.Proxy) Same engine inside your app — inspect, modify, or reverse-proxy traffic NuGet · Library
Standalone CLI & Kubernetes edge (titanium / twp) Reverse / edge proxy from YAML, Docker, or Helm Download CLI · CLI · Kubernetes
Automatic block & TLS-fingerprint tunneling When a server blocks the proxy, we detect it and tunnel that traffic Features
Visual MITM traffic debugger (Titanium Inspector) Session grid, inspectors, AutoResponder, breakpoints, HAR export Download Inspector · Inspector
Benchmarked speed at scale Practical reverse RPS vs peers on the same harness Performance · Site charts
Optional control-plane add-ons (Titanium.Plus) xDS, GeoIP, caching, rate limiting, health probes, dashboard titanium update --plus · Plus

Run it in 30 seconds

Library (.NET)

dotnet add package Titanium.Web.Proxy
# Prerelease / beta:
dotnet add package Titanium.Web.Proxy --prerelease

Explicit HTTP(S) proxy on 127.0.0.1:8000 that logs each requested URL:

using System;
using System.Net;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Titanium.Web.Proxy;
using Titanium.Web.Proxy.EventArguments;
using Titanium.Web.Proxy.Models;

using var proxyServer = new ProxyServer();

proxyServer.Logging.MinimumLevel = LogLevel.Information;
proxyServer.BeforeRequest += OnRequest;

var endPoint = new ExplicitProxyEndPoint(IPAddress.Loopback, 8000, decryptSsl: true);
proxyServer.AddEndPoint(endPoint);

// Create and trust the root certificate used to decrypt HTTPS traffic.
proxyServer.CertificateManager.EnsureRootCertificate(
    userTrustRootCertificate: true,
    machineTrustRootCertificate: false);

proxyServer.Start();
proxyServer.Logger.LogInformation("Proxy listening on 127.0.0.1:8000. Press Enter to stop.");
await Console.In.ReadLineAsync();
proxyServer.Stop();

Task OnRequest(object sender, SessionEventArgs e)
{
    proxyServer.Logger.LogInformation("{Url}", e.HttpClient.Request.Url);
    return Task.CompletedTask;
}

Point your client at 127.0.0.1:8000 as its HTTP and HTTPS proxy.

CLI (reverse / edge proxy)

Create twp.yaml, then validate and run:

schemaVersion: "7.1"
listeners:
  - host: "127.0.0.1"
    port: 8000
    # false = plain reverse proxy (no HTTPS decrypt)
    decryptSsl: false
    forwardHost: "127.0.0.1"
    forwardPort: 8080
titanium test -c twp.yaml
titanium run -c twp.yaml

Titanium Inspector screenshot

Basic console proxy screenshot

Go deeper

Full catalog: Features. What is supported, partial, and not supported: capability coverage. Protocol coverage: protocol support matrix. HTTP/3 packaging: HTTP/3 wiki.

Performance

Tiny keep-alive GET (~56 B) on common reverse wires, plus WebSocket and unary gRPC:

Practical reverse proxy throughput on Linux (tiny requests)

Heavier reverse load (64 KB GET/POST on typical wires):

Practical reverse proxy throughput on Linux (64 KB)

RPS is requests per second (gRPC bars are RPC/s). Compared on the same harness vs YARP, nginx, HAProxy, and Envoy. See Performance.

Installation

Inspector and CLI (Windows, Linux, macOS): use Download — MSI / DMG / AppImage / .deb / .rpm / zip. Short walkthrough: Install.

After the CLI is on your PATH (or in the current folder):

titanium run -c twp.yaml
titanium test -c twp.yaml
titanium version --check
titanium update

titanium run is foreground (Ctrl+C to stop). Boot persistence: titanium service install -c twp.yaml — CLI — service. Each CLI zip also includes a twp alias.

Optional Plus: titanium update --plus, then plus.enabled: true — Plus.

Container and Helm: the CLI ships as a hardened image (ghcr.io/justcoding121/titanium-web-proxy, linux/amd64 and linux/arm64) and charts under deploy/helm/ (also Release .tgz and oci://ghcr.io/justcoding121/charts) — Kubernetes. Gateway API / Ingress: Gateway API.

docker run --rm -p 8080:8080 --read-only --tmpfs /tmp -v "$PWD/conf:/etc/titanium:ro" ghcr.io/justcoding121/titanium-web-proxy:latest
helm install titanium deploy/helm/titanium -n proxy --create-namespace -f my-values.yaml

Upgrading from 7.x

Moving from 7.x to 8.0: migration guide · website.

Trust and native scripting

Trusting a generated root certificate changes the current user's certificate store — only do this on a machine you control.

Lua 5.4 and proxy-wasm scripting ship with the CLI (titanium scripting-deps). Container images include Lua and Wasmtime natives per RID. Details: Scripting.

What you can do

  • Decrypt and inspect HTTPS in a native desktop Inspector on Windows, macOS, and Linux — AutoResponder, Map Local/Remote, breakpoints, Composer, HAR, curl/fetch
  • Speak modern HTTP — HTTP/2 by default, optional HTTP/3, WebSocket, gRPC, SSE, GraphQL rules in the same grid
  • Run the same engine as a reverse / edge proxy from the CLI — YAML routes, load balancing and failover, retries, rate limits, response compression, gRPC-Web, TCP and UDP relay, ACME, live reload, Lua 5.4 and proxy-wasm scripting (titanium scripting-deps)
  • Deploy on Kubernetes with a hardened container image, Helm charts (git, Release .tgz, or OCI), probes, a Gateway API / Ingress controller, and an optional Manager control plane; hot restart for TCP without a gap
  • Observe it with Prometheus text, OTLP traces and metrics, and an access log; Plus adds a dashboard, OpenID Connect login, a response cache, fleet rate limits, xDS, and WAF screening
  • Embed in .NET via NuGet; when a server blocks the proxy (TLS fingerprinting or other reasons), we detect it and automatically tunnel that traffic

Examples and documentation

Support and contributing

Code quality

Quality Gate Coverage Lines of Code Bugs Vulnerabilities Code Smells Security Rating Reliability Rating Maintainability Rating Duplicated Lines Technical Debt

Maintainers

Actively maintained by justcoding121. Past collaborator: honfika.

License

Titanium.Web.Proxy, Titanium.Cli, Titanium.Manager, Titanium.Gateway, docs, and this website are MIT. Titanium Inspector, Titanium.Plus, Titanium.Xds, and Titanium.Cli.GeoIp are PolyForm Noncommercial 1.0.0. Product overview: titaniumproxy.com · Editions & licenses.

Vendored xDS protos keep their Apache-2.0 text in src/Titanium.Xds/LICENSE.Apache-2.0.txt and src/Titanium.Xds/NOTICE. Third-party notices for the MIT library are in src/Titanium.Web.Proxy/NOTICE.

Folder License
src/Titanium.Web.Proxy, src/Titanium.Web.Proxy.Abstractions, src/Titanium.Web.Proxy.Configuration, src/Titanium.Web.Proxy.Scripting, src/Titanium.Cli, src/Titanium.Manager, src/Titanium.Gateway, examples, website, docs, wiki, tools, deploy, and tests other than the four PolyForm test projects MIT
src/Titanium.Plus, src/Titanium.Inspector, src/Titanium.Xds, src/Titanium.Cli.GeoIp, tests/Titanium.Plus.Tests, tests/Titanium.Inspector.Tests, tests/Titanium.Xds.Tests, tests/Titanium.Cli.GeoIp.Tests PolyForm Noncommercial 1.0.0

About

A cross-platform high performing HTTP(S) proxy server in C#.

Topics

Resources

Contributing

Security policy

Stars

2.0k stars

Watchers

4 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages