Shuttle: The Go Proxy That Puts Traffic Manipulation First

Hook

Most proxy tools treat traffic inspection as an afterthought. Shuttle built its entire architecture around the assumption that you want to intercept, modify, and mock HTTP traffic—then added multi-protocol proxy support on top.

Context

The proxy tool landscape is weirdly bifurcated. On one side, you have enterprise proxies like Squid and HAProxy focused on performance and stability. On the other, you have debugging tools like mitmproxy and Charles Proxy built for traffic inspection. If you wanted both—say, to route traffic through multiple upstream shadowsocks servers while simultaneously capturing and modifying HTTP requests—you'd typically run two separate tools and chain them together.

Shuttle emerged from this friction point. It's a Go-based proxy that treats MITM capabilities, server group management, and rule-based routing as co-equal concerns. The core thesis is simple: developers working behind restrictive networks or building distributed systems need to both route traffic intelligently and understand what that traffic contains. Rather than forcing users to cobble together a mitmproxy + v2ray setup, Shuttle provides a unified control plane with a web dashboard, three listening ports (HTTP/HTTPS on 8080, SOCKS5 on 8081, web UI on 8082), and a rule engine that determines both where traffic goes and whether it gets inspected along the way.

Technical Insight

Shuttle's architecture is surprisingly modular for a tool that does so much. At the core is a rule-based routing engine that evaluates every connection against a series of matchers—domain suffix, keyword, IP-CIDR, and GEO-IP rules. Each rule maps to a server group, which can contain multiple upstream proxy servers. What makes this interesting is the server selection logic: Shuttle continuously measures RTT (round-trip time) for each server and automatically promotes the fastest one, while still allowing manual overrides through the web UI.

The MITM implementation is where things get technically dense. When Shuttle intercepts an HTTPS connection, it performs a man-in-the-middle attack against itself—generating a certificate on-the-fly for the target domain, signed by a root CA that you install in your system trust store. This lets Shuttle decrypt, inspect, and modify traffic before re-encrypting and forwarding it. Here's what a basic configuration looks like:

general:
  http-port: 8080    # HTTP/HTTPS proxy
  socks-port: 8081   # SOCKS5 proxy
  web-port: 8082     # Dashboard
  
dns:
  static:
    api.internal: 192.168.1.100
  direct:              # Local DNS for these domains
    - "*.local"
  remote:              # Use proxy's DNS
    - "*"
    
servers:
  - name: "us-west"
    protocol: shadowsocks
    server: us.example.com:8388
    cipher: chacha20-ietf-poly1305
    password: "secret"
    
  - name: "us-east"
    protocol: shadowsocks
    server: us-east.example.com:8388
    cipher: chacha20-ietf-poly1305
    password: "secret"
    
server-groups:
  - name: "usa"
    servers: ["us-west", "us-east"]
    selection: rtt     # or 'manual'
    
rules:
  - match: DOMAIN-SUFFIX,github.com
    target: usa
    
  - match: DOMAIN-KEYWORD,google
    target: usa
    
  - match: GEOIP,US
    target: usa
    
  - match: IP-CIDR,192.168.0.0/16
    target: DIRECT

The DNS resolution strategy is particularly clever. Shuttle offers three modes: static (hardcoded IP mappings), direct (use local DNS), and remote (query DNS through the proxy). This matters because DNS poisoning is a common censorship technique. By routing DNS queries through the proxy for certain domains, you can bypass local DNS tampering. The configuration above shows all three in action—static mapping for internal APIs, direct resolution for local domains, and remote resolution (through the proxy) for everything else.

What separates Shuttle from simpler proxies is its traffic manipulation layer. Beyond just inspecting requests, you can define URL rewrite rules and mock responses. This is invaluable for QA testing:

mitm:
  rules:
    - match: api.production.com
      action: rewrite
      target: api.staging.com
      
    - match: /v1/feature-flag
      action: mock
      response: |
        {
          "newFeature": true,
          "rolloutPercentage": 100
        }

With this configuration, Shuttle intercepts requests to api.production.com and silently redirects them to staging, while any call to the feature flag endpoint returns a mocked response with the feature enabled. Your application remains unchanged—it thinks it's talking to production—but you can test edge cases without deploying code.

The server group RTT selection is implemented through periodic health checks. Every 30 seconds (configurable), Shuttle sends lightweight probes through each server in a group and measures response time. The fastest server becomes active, with automatic failover if it becomes unresponsive. This is particularly useful when working with commercial VPN services that provide multiple endpoints—Shuttle automatically uses the best one based on real-time conditions rather than geography or guesswork.

The web dashboard deserves mention because it's not just chrome around the core functionality. It provides real-time connection monitoring, per-domain traffic statistics, and server group health visualization. More importantly, it lets you temporarily override RTT-based selection to manually test specific upstream servers, and you can enable/disable rules on the fly without restarting the proxy. This interactive debugging capability is rare in CLI-first tools.

Gotcha

The UDP limitation is significant and non-negotiable. Shuttle explicitly doesn't support UDP proxying, which eliminates several important use cases. If you're trying to proxy DNS-over-UDP, gaming traffic, or QUIC-based HTTP/3, you're out of luck. This is particularly frustrating because many modern applications are moving to QUIC, and Shuttle will silently fail to proxy those connections—your browser will fall back to HTTP/2, which works, but you lose the performance benefits and might not realize what's happening.

The MITM certificate management is also glossed over in the documentation. The README explains that you need to install a root CA certificate, but it doesn't discuss the security implications deeply. This certificate gives Shuttle—and anyone who obtains it—the ability to decrypt all your HTTPS traffic. If you're using Shuttle on a work machine or shared system, you need to understand the threat model. The certificate should be treated like a password, rotated periodically, and definitely not checked into version control. The project doesn't provide tooling for certificate rotation or secure storage, leaving this as an exercise for the user.

Maintenance velocity is the elephant in the room. With 2,050 stars, Shuttle has clearly resonated with users, but the last significant activity and version references (v1.0.1 configurations, links to Slack/Telegram channels) suggest the project may not be actively maintained. There's no clear deprecation notice, but there's also no evidence of ongoing feature development or security updates. For a tool that performs MITM attacks and handles sensitive traffic routing, this is concerning. You should assume you're adopting legacy software and plan accordingly—fork it if you need custom features, and be prepared to debug Go code when (not if) something breaks with a newer dependency or operating system version.

Verdict

Use Shuttle if you're a developer or QA engineer who needs to both route traffic through multiple proxies and actively inspect/modify that traffic. It's ideal for testing applications against different API environments, debugging production issues by intercepting and rewriting requests locally, or working behind restrictive networks that require intelligent routing rules combined with traffic visibility. The RTT-based server selection and GEO-IP routing make it powerful for optimizing connections across multiple upstream proxies. Skip it if you need UDP support, require active maintenance and security updates for production use, or want something simpler—most users just need either a proxy or a debugging tool, not both. Also skip if you're uncomfortable with the security implications of MITM certificates or don't want to maintain a potentially abandoned project. Consider Clash for pure proxy functionality with active development, or mitmproxy if traffic inspection is your primary goal and you can sacrifice the multi-server management features.