How to Use Upstream Proxy and WebSocket Protobuf Decoding in Rockxy

Rockxy is a native, open-source macOS proxy debugger for inspecting HTTP, HTTPS, WebSocket, and GraphQL traffic — locally, with no cloud account. Two new capabilities extend what you can do with it in real-world network environments:

• Upstream Proxy (External Proxy) — route all outbound traffic from Rockxy through a second proxy server, such as a corporate gateway, VPN proxy, staging network proxy, or a chained security tool.
• WebSocket Protobuf heuristic decoding — decode binary WebSocket frames using Protocol Buffers wire-format parsing, without needing a .proto schema file.

This guide walks through both features end to end. It is written for mobile app developers, backend engineers, QA engineers, and API platform teams who need to debug traffic behind corporate proxies, VPNs, test networks, or chained proxy setups — and for anyone debugging realtime services that send binary WebSocket messages.

What is an upstream proxy?

Rockxy acts as a local HTTP/HTTPS proxy on your Mac. It intercepts outbound requests from apps and devices, lets you inspect and modify them, then forwards them to their destinations. An upstream proxy — sometimes called an external proxy or chained proxy — is a second proxy server that sits between Rockxy and the internet.

When you enable upstream proxy, every outbound request that Rockxy would normally send directly is instead forwarded through the configured proxy server first. The full traffic path looks like this:

App / device
    ↓
Rockxy (captures, inspects, filters)
    ↓
Upstream Proxy (corporate gateway / VPN / security proxy)
    ↓
Internet / API server

Rockxy retains full capture and inspection capabilities at its layer. The upstream proxy handles the outbound routing. The two roles are independent.

When should you use upstream proxy?

Use upstream proxy when your network requires it or when you are reproducing an environment that uses one:

Step-by-step: Enable External Proxy in Rockxy

Follow these steps exactly. Each step includes what to expect so you can confirm you are in the right place before moving forward.

HTTP proxy vs HTTPS proxy — which one to choose

The protocol setting describes how Rockxy connects to the upstream proxy server. It does not limit what kind of app traffic Rockxy can forward. Both options support HTTP and HTTPS app traffic.

If you are unsure, start with HTTP. HTTPS proxy is only needed when the proxy server itself requires an encrypted inbound connection — not simply because your app traffic is HTTPS.

Diagnosing a failed test connection

Run the connection test before starting a capture session. If it fails, work through these checks in order:

Bypass rules — controlling which hosts skip the upstream proxy

Bypass rules define a list of hostnames that Rockxy routes directly, bypassing the upstream proxy entirely. This prevents local development traffic and internal APIs from accidentally going through an external server.

Localhost bypass is on by default. Traffic to localhost and 127.0.0.1 always goes direct. Only remove this rule if you explicitly need localhost traffic forwarded through the upstream proxy.

Bypass rules support two wildcard characters:

A practical bypass list for a developer working on a local API against a staging network proxy:

# Always bypass local dev
localhost
127.0.0.1

# Bypass all subdomains of your local dev domain
*.local.dev

# Bypass specific internal API host
api.internal.test

# Bypass staging backend to test direct path comparison
staging-api.example.com

What is WebSocket Protobuf decoding?

WebSocket is the transport layer used by most realtime app features — live data feeds, multiplayer game state, chat, collaboration tools, financial tickers. A large share of these systems encode their WebSocket payloads using Protocol Buffers (Protobuf), a binary serialization format from Google. Protobuf is compact and efficient on the wire, but completely unreadable to humans without decoding.

Without a decoder, a Protobuf WebSocket frame in a standard proxy debugger looks like this:

0a 07 63 72 65 61 74 65 64 10 2a 1a 0c 0a 08 75 73 65 72 5f 31 32 33 10 80 c0 c3 d5 06

Rockxy's heuristic Protobuf decoder reads the wire format directly and presents a structured field tree — without requiring a .proto schema file. The same bytes above become:

field 1 (length-delimited) → "created"
field 2 (varint)           → 42
field 3 (message)
  field 1 (length-delimited) → "user_123"
  field 2 (varint)           → 1716537600

Field names are stored in the .proto schema, not in the encoded binary, so heuristic mode shows field numbers and wire types instead. That is usually enough to verify field presence, check values, identify nested messages, and compare frames across requests and responses.

What heuristic decoding shows you

Step-by-step: Decode Protobuf WebSocket frames in Rockxy

End-to-end workflow: iOS or Android app behind an upstream proxy

This is the most common combined workflow — a mobile app that routes through a corporate or test network proxy, with binary WebSocket traffic you need to inspect.

1. Configure the device proxy. On an iOS device or simulator, go to Wi-Fi settings → HTTP Proxy → Manual. Set the server to your Mac's LAN IP address and the port to Rockxy's active proxy port (shown in the Rockxy toolbar). On Android, do the same in Wi-Fi → Modify network → Advanced options → Proxy → Manual.
2. Install the Rockxy CA certificate on the device. Navigate to rockxy.local/cert (or the equivalent URL shown in Rockxy) on the device browser. Download and install the certificate. On iOS, also go to Settings → General → About → Certificate Trust Settings and enable full trust. This allows Rockxy to inspect wss:// frames.
3. Enable External Proxy in Rockxy. Go to Tools → Proxy Settings → Use External Proxy. Enter your corporate or staging upstream proxy host and port.
4. Add bypass rules. Keep localhost in the bypass list. Add any internal API hosts that should stay on a direct path.
5. Test the upstream proxy connection. Click Test Connection and confirm it passes before starting capture.
6. Start capture and reproduce the app flow. Open the app on the device and navigate to the feature that triggers HTTP, HTTPS, and WebSocket traffic.
7. Inspect HTTP and HTTPS traffic. Select rows in Rockxy to inspect request headers, response bodies, status codes, and timing.
8. Inspect WebSocket frames and decode Protobuf. Select the WebSocket connection. For binary frames, open the Protobuf tab. Compare field values across frames to verify protocol behavior.

End-to-end workflow: Debugging a realtime WebSocket API

Use this when you are building or testing a realtime feature — a collaborative editor, a live dashboard, a financial data feed, a game server — and need to understand the binary message protocol.

1. Start capture in Rockxy. Click Start. Filter by host if the capture is noisy.
2. Trigger the WebSocket session. Open the app and navigate to the realtime feature. The WebSocket connection appears in the traffic list within seconds.
3. Select the connection and review the frame list. Check frame direction (↑ client → server, ↓ server → client), frame size in bytes, and timestamps. Large or frequent frames are good candidates for closer inspection.
4. Open a binary frame and switch to Protobuf view. If the payload is Protobuf wire format, the decoder activates automatically. The field tree appears in the inspector.
5. Verify field structure and values. Cross-reference field numbers with what you know about the protocol. Check that numeric values are in the expected range, string fields are valid UTF-8, and nested messages expand to the expected depth.
6. Compare frames across the session. Select multiple frames — for example, the initial connection message and a subsequent update message — and compare their field structure. Field numbers that appear in some frames but not others indicate optional fields.
7. Use raw or hex for undecoded frames. Control frames, ping/pong frames, compressed frames, and non-Protobuf binary frames will not decode. Switch to Raw or Hex and inspect manually.

Troubleshooting

Use External Proxy does not stay checked after I enable it

Rockxy requires a valid host and port before enabling the feature. If either is missing, clicking Use External Proxy opens External Proxy Settings instead of activating. Enter a valid upstream proxy host and port, save, then enable the toggle again. The menu item shows a checkmark only when the configuration is complete.

The upstream proxy connection test fails

Work through these checks in order: confirm the host and port are correct; confirm your Mac can reach the proxy server (VPN connected, corporate Wi-Fi active); confirm the proxy server allows CONNECT tunneling for HTTPS traffic; check whether your Mac's local firewall or an endpoint security tool is blocking the outbound connection on the proxy port.

Localhost traffic is not going through the upstream proxy

This is intentional. Rockxy bypasses the upstream proxy for localhost and 127.0.0.1 by default, protecting local development traffic from inadvertently routing through an external server. Remove the localhost bypass rule in External Proxy Settings only if you intentionally need it forwarded.

A bypass rule is not matching the host I expect

Check spelling first. Then verify wildcard placement: *.example.com matches all subdomains of example.com but not example.com itself — add both if needed. Remember ? matches exactly one character, not a segment.

A WebSocket frame does not decode as Protobuf

Not all binary WebSocket frames are Protobuf. Common alternatives include gzip-compressed JSON (1f 8b magic bytes), MessagePack, CBOR, custom binary protocols, or encrypted payloads. Heuristic decoding requires valid Protobuf wire format — if the bytes do not follow that structure, the decoder will not produce a tree. Use the Raw or Hex tab to inspect the bytes manually and identify the actual encoding.

The Protobuf tree shows only field numbers, not names

Field names exist only in the .proto schema. The encoded binary contains only the field number and value — names are not transmitted on the wire. Heuristic decoding gives you the full structure, including field numbers, wire types, and values. To get human-readable names, you need the schema for that service.

Frequently asked questions