​

Traffic Rules

Rockxy’s rule engine intercepts matching requests in the proxy pipeline and applies actions before they reach the server or return to the client. Rules are evaluated in priority order against every HTTP and HTTPS request that passes through the proxy.

​

Entry Points

​

Rule Types

​

Creating Rules

1. Open the Rules sidebar from the left navigation panel.
2. Click Add Rule at the bottom of the rule list.
3. Configure the match condition — URL pattern, HTTP method, or header match.
4. Select the action type from the dropdown (Breakpoint, Map Local, Map Remote, Block, Throttle, or Modify Header).
5. Fill in the action-specific configuration (file path, target URL, delay, header operations, etc.).
6. Set the rule priority by dragging it to the desired position in the list.
7. Click Save. The rule takes effect immediately for all new requests.

​

Rule Matching

Each rule has a match condition that determines which requests it applies to. Match conditions support three criteria:

• URL Pattern — a regular expression matched against the full request URL (scheme, host, path, query string).
• HTTP Method — restrict to GET, POST, PUT, DELETE, PATCH, or any other method.
• Header Name/Value — match requests that contain a specific header with an optional value pattern.

Rules are evaluated in priority order. The first rule whose match condition is satisfied wins — subsequent rules are skipped for that request.

​

Breakpoints

Breakpoints pause a request at the proxy layer so you can inspect and edit it before it continues. Workflow:

1. A request matching the breakpoint rule arrives at the proxy.
2. Rockxy pauses the request and queues it in the Breakpoints window (Cmd+Shift+B).
3. The window uses a two-column layout: a queue list on the left showing all paused requests (with elapsed time), and an editor on the right with editable URL, method, headers, query parameters, and body.
4. Modify any field, then click Execute to forward the modified request, Cancel to drop it silently, or Abort to return a 503 to the client.
5. Breakpoints can be set to pause on the request phase, the response phase, or both. Response breakpoints let you edit the status code, headers, and body before the response reaches the client.
6. Multiple requests can be paused simultaneously — resolve them individually or use Resolve All.

​

Map Local

Map Local serves a response from a file on disk instead of forwarding the request to the server. Open the dedicated editor from Tools > Map Local… or right-click a captured request and choose Map Local… to create a rule with prefilled fields. Quick-create: Right-click any captured request in the traffic list and choose Map Local…. The Map Local window opens with the editor prefilled from the selected request — URL pattern, method, and name are auto-populated. Match modes: Map-to modes: Configuration:

• File/Directory Path — absolute path to the local file or directory.
• Status Code — HTTP status code to return (default: 200).
• Content-Type — automatically inferred from the file extension (e.g., .json → application/json, .html → text/html). Applies to both file and directory modes.

Use cases:

• Mock API responses during frontend development without a running backend.
• Test error states by mapping an endpoint to a file containing an error response.
• Work offline by mapping critical endpoints to cached response files.
• Snapshot a live response and iterate on it locally without re-fetching.

​

Map Remote

Map Remote redirects matching requests to a different server by rewriting URL components. Open the dedicated editor from Tools > Map Remote… or right-click a captured request and choose Map Remote… to create a rule with prefilled fields. Quick-create: Right-click any captured request in the traffic list and choose Map Remote…. The Map Remote window opens with the editor prefilled from the selected request. Structured destination editing: Each URL component can be overridden independently. Leave a field blank to keep the original request value. Preserve Host Header — when enabled, the Host header sent to the destination server retains the original request’s host value instead of the remapped host. This is useful when the backend validates the Host header for routing or security. Match modes: Examples: HTTP ↔ HTTPS remapping — Map Remote supports cross-protocol redirection. A plain HTTP request can be remapped to an HTTPS upstream, and vice versa. The proxy handles TLS negotiation automatically. Use cases:

• Route production API traffic to a staging or development server.
• Test your app against a different API version without code changes.
• Redirect CDN requests to a local development server.
• Switch between environments (staging, QA, production) by changing only the host.

​

Block

Block prevents matching requests from reaching the server and returns a configurable HTTP status code (default: 403 Forbidden). Use cases:

• Block analytics and tracking endpoints during debugging to reduce noise in the traffic list.
• Block third-party ad or SDK requests to isolate your app’s own network behavior.
• Simulate server-side blocking to test client error handling.

​

Throttle

Throttle adds artificial delay to matching requests. The proxy holds the request for the configured duration before forwarding it, simulating slow network conditions. Configuration:

• Delay (ms) — milliseconds of latency added to each matching request.

​

Modify Header

Modify Header changes request or response headers for matching requests. Each rule can contain multiple header operations that are applied in order. Open the dedicated editor from Tools > Modify Headers… to create and manage header modification rules. Operations: Phase — each operation targets a specific direction: Creating a Modify Header rule:

1. Open Tools > Modify Headers…
2. Click + or the Add Rule toolbar button.
3. Enter a name and a URL pattern (regex). Use .* to match all traffic.
4. Add one or more header operations. For each, pick the phase, operation type, header name, and value.
5. Click Add Rule. The rule takes effect immediately.

Operations within a rule are applied top to bottom. If two operations modify the same header, the later one wins. Presets — common header rules you can create instantly from the Presets menu: Use cases:

• Add authentication headers to test protected endpoints without modifying your app.
• Strip tracking or fingerprinting headers from responses.
• Inject CORS headers to bypass cross-origin restrictions during local development.
• Add feature flags via custom headers to toggle server behavior.
• Remove caching headers to force fresh responses during debugging.

​

Rule Persistence

Rules are stored as JSON at ~/Library/Application Support/Rockxy/rules.json. This file is human-readable and version-control friendly. Import/Export:

• Export — right-click a rule or selection of rules and choose Export Rules. Saves a .json file you can share.
• Import — click Import Rules in the Rules sidebar and select a .json file. Imported rules are appended to the existing list.

Share rule files between machines or team members to standardize debugging configurations.

​

Rule Priority

Rules are evaluated top to bottom. The first matching rule wins — no further rules are checked for that request.

• Reorder by dragging rules in the sidebar list.
• Disable a rule without deleting it by toggling the checkbox next to its name.
• Delete by right-clicking and selecting Delete Rule, or pressing the Delete key with the rule selected.

​

Next Steps