Rockxy Flutter Sample Guidance

This sample shows how to route Flutter HTTP traffic through Rockxy while keeping certificate and proxy changes limited to debug builds.

Flutter apps do not always inherit a system proxy automatically. The reliable manual path is:

1. choose the Rockxy proxy host for the runtime running the app;
2. copy Rockxy's active proxy port from the Rockxy app into the Flutter client;
3. run the local demo API on this Mac;
4. send one known request and confirm it appears in Rockxy.

For HTTPS inspection, complete the iOS or Android certificate trust path after the HTTP capture path is working.

Runtime Proxy Hosts

Runtime	Host value
iOS Simulator	127.0.0.1:<Rockxy port>
macOS desktop Flutter	127.0.0.1:<Rockxy port>
Android Emulator	10.0.2.2:<Rockxy port>
Physical iPhone, iPad, or Android device	<Device Proxy LAN host>:<Rockxy port>

The active Rockxy port is shown in the Rockxy toolbar. For physical devices, use the Device Proxy LAN host shown in Developer Setup Hub and keep the device on the same local network as the Mac.

Only choose Android Emulator when the Flutter app itself is running inside an Android emulator. If you run this sample as a macOS desktop app, choose iOS Simulator / macOS desktop; 10.0.2.2 is an Android-emulator-only route back to the Mac.

Step-By-Step Setup

1. Start Rockxy and keep capture enabled.
2. Open Developer Setup Hub > Flutter.
3. Pick the runtime that matches where the Flutter app is running.
4. Copy the active Rockxy proxy port from the Rockxy toolbar.
5. Paste that value into the sample app's Rockxy port field.
6. Set the Demo API base URL separately from the Rockxy proxy target.
7. Run the local demo API:

fvm dart run tool/rockxy_demo_api.dart --port 43210

8. Run the Flutter sample and run Known-good app startup.
9. Confirm Rockxy captures requests with X-Rockxy-Lab-Run-Id, X-Rockxy-Scenario-Id, and X-Rockxy-Step-Id headers.

For HTTPS app traffic, also install and trust the Rockxy certificate for that runtime:

• iOS Simulator: install/trust the certificate in the simulator.
• Physical iPhone or iPad: install the certificate profile and enable full trust in iOS settings.
• Android Emulator: install the user certificate and run a debug build that trusts user CAs.
• Physical Android device: set the Wi-Fi proxy to the Device Proxy LAN host, install the user certificate, and run a debug build that trusts user CAs.

Use This Sample

Install FVM once, then run the sample through the project-pinned Flutter SDK:

brew install fvm
git clone https://github.com/RockxyApp/Rockxy-Flutter-Sample-Guidance.git
cd Rockxy-Flutter-Sample-Guidance
fvm use stable
fvm flutter pub get
fvm dart run tool/rockxy_demo_api.dart --port 43210

In another terminal, run the Flutter app:

fvm flutter run

If you want to target a specific runtime, start the simulator or emulator first, then choose the matching Flutter device:

Start Each Runtime

List the devices Flutter can see:

fvm flutter devices

Run the sample as a macOS desktop app:

fvm flutter run -d macos

Run the sample in iOS Simulator:

open -a Simulator
fvm flutter run -d ios

If -d ios is not specific enough on your machine, pick the simulator ID from fvm flutter devices and run with that device ID instead.

Run the sample in Android Emulator:

fvm flutter emulators
fvm flutter emulators --launch <android_emulator_id>
fvm flutter run -d emulator-5554

If you prefer the Android SDK emulator command directly, start an AVD first and then run Flutter on the connected emulator:

emulator -avd <avd_name>
fvm flutter run -d emulator-5554

Choose the matching runtime inside the sample app after it launches:

• macOS desktop: iOS Simulator / macOS desktop
• iOS Simulator: iOS Simulator / macOS desktop
• Android Emulator: Android Emulator
• Physical device: Physical device

Before pressing Run Scenario, copy the active proxy port from Rockxy and paste it into the sample app's Rockxy port field. Do not assume 9090; Rockxy can run on another configured or fallback port, such as 8888.

The repository tracks .fvmrc, so you can switch versions later without changing global Flutter:

fvm use 3.32.8
fvm flutter doctor
fvm flutter test

The generated Android debug target already includes the same debug-only trust configuration shown in snippets/android/app/src/debug.

Run The Debugging Lab

Use harmless, clearly fake data when recording a Rockxy demo. The sample app now runs scenario groups instead of a single request. Each step emits correlation headers so you can search and filter in Rockxy:

• X-Rockxy-Lab
• X-Rockxy-Lab-Run-Id
• X-Rockxy-Scenario-Id
• X-Rockxy-Step-Id
• X-Rockxy-Client
• X-Rockxy-Runtime
• X-Request-ID

Rockxy can capture this loopback demo when the Flutter client explicitly routes the request through Rockxy. Do not rely on the operating system proxy alone for localhost traffic because system bypass settings commonly exclude localhost and 127.0.0.1.

Scenario Groups

Use these scenario groups to demonstrate Rockxy features together:

• Known-good app startup: baseline capture, headers, response body, timing.
• Wrong backend environment: use Map Remote to rewrite environment traffic.
• Expired token and retry: inspect auth headers, modify headers, and replay.
• Checkout body and response contract: inspect POST bodies and schema mismatch.
• Slow and failed network calls: use status filters, Block List, and latency.
• Scripted response mutation: use scripting when static rules are not enough.

Run one scenario first, then use Run All when you want a full capture timeline. In Rockxy, filter by the run ID shown in the app.

Case-By-Case Workbook

Use the sample as a guided debugging workbook. Move from the easy cases to the harder ones so each step has a known baseline:

Case	Sample step	Rockxy feature	Evidence to collect
0	app-startup/bootstrap	Capture and inspector	URL, method, headers, 200 JSON body, timing
1	app-startup/runtime-diagnostic	Runtime proxy setup	127.0.0.1, 10.0.2.2, or LAN host matches the runtime
2	Run All	Filters and Allow List	Rows isolated by X-Rockxy-Lab-Run-Id and scenario headers
3	Custom HTTPS probe	SSL Proxying	Decrypted HTTPS headers and body for an included trusted host
4	wrong-environment/production-config	Map Remote	Wrong environment marker rewritten to the intended upstream
5	auth-recovery/*	Header inspection, Modify Header, Breakpoints	Expired token, refresh response, successful retry
6	checkout-contract/checkout-mismatch	Replay, Edit-and-Repeat, Compose	Edited POST body changes backend result
7	checkout-contract/shape-mismatch	Map Local	Fixture response replaces malformed backend payload
8	network-failure/analytics	Block List	Optional endpoint can return 403 or drop without breaking the flow
9	network-failure/slow-checkout	Network Conditions	Request duration increases by configured latency
10	network-failure/server-error	Status filtering and response inspector	500 payload is visible and attributable
11	scripted-mock/pricing-experiment	Scripting	Response body can be mutated for an experiment/mock case
12	Repeat cases with Dio	Dio proxy debugging	Same scenario IDs appear with X-Rockxy-Client: dio-5

If a case fails, keep the failed capture. The case number and correlation headers make it easier to decide whether the next fix belongs in the sample, the Flutter app code, Rockxy's setup UX, a rule behavior, or the backend contract.

Map Local Fixtures

The fixtures/rockxy_demo directory contains deterministic JSON responses for Map Local:

• profile.json
• products.json
• cart.json
• checkout.json
• errors.json

Map /rockxy-demo/schema-mismatch to one of these fixtures to prove whether the Flutter UI handles the expected response contract.

Generate Your Own Safe Demo URLs

Keep demo values descriptive and fake. Prefer IDs such as demo-user-001, demo-cart-2026, and sandbox_card instead of names, email addresses, access tokens, session cookies, or production identifiers.

final demoUrl = Uri.http(
  '127.0.0.1:43210',
  '/rockxy-demo/products',
  {
    'category': 'coffee',
    'currency': 'USD',
    'page': '1',
    'source': 'flutter_debug_sample',
  },
);

Then paste demoUrl.toString() into the Advanced custom probe field or pass it directly to the client code in lib/rockxy_debug_proxy.dart.

Copy The Client Setup

The reusable code lives in lib/rockxy_debug_proxy.dart. Copy that file into a debug-only area of your app, choose the runtime, then create the client that your app already uses.

Dart HttpClient

final settings = RockxyDebugProxySettings(
  runtime: RockxyRuntime.localAppleRuntime,
  // Replace this with the active proxy port copied from Rockxy.
  port: 8888,
  physicalDeviceHost: '',
);

final client = settings.createHttpClient();
final request = await client.getUrl(
  Uri.parse('http://127.0.0.1:43210/rockxy-demo/bootstrap'),
);
final response = await request.close();
client.close(force: true);

package:http

final settings = RockxyDebugProxySettings(
  runtime: RockxyRuntime.androidEmulator,
  // Replace this with the active proxy port copied from Rockxy.
  port: 8888,
  physicalDeviceHost: '',
);

final client = settings.createPackageHttpClient();
final response = await client.get(
  Uri.parse('http://127.0.0.1:43210/rockxy-demo/bootstrap'),
);
client.close();

Dio 5

final settings = RockxyDebugProxySettings(
  runtime: RockxyRuntime.physicalDevice,
  // Replace this with the active proxy port copied from Rockxy.
  port: 8888,
  physicalDeviceHost: '192.168.1.10',
);

final dio = settings.createDio();
final response = await dio.getUri(
  Uri.parse('http://127.0.0.1:43210/rockxy-demo/bootstrap'),
);
dio.close(force: true);

What To Edit

The app has a scenario lab where you can choose:

• runtime: local Apple runtime, Android Emulator, or physical device;
• Rockxy port copied from the active Rockxy app;
• Device Proxy LAN host for physical devices;
• Demo API base URL, kept separate from the Rockxy proxy target;
• client type: Dart HttpClient, package:http, or Dio 5.
• scenario group, run selected, run all, or send a custom GET probe.

The reusable implementation lives in:

• lib/rockxy_debug_proxy.dart
• lib/rockxy_lab_contract.dart
• lib/rockxy_lab_scenarios.dart
• lib/rockxy_lab_runner.dart
• lib/rockxy_lab_screen.dart

Debug-Only Safety

This sample intentionally uses debug-only certificate bypass code so Rockxy can inspect HTTPS while you are learning the setup path.

Do not ship release builds with:

• badCertificateCallback;
• Dio validateCertificate returning true;
• Android user-CA trust in release manifests.

For Android, keep user-CA trust under app/src/debug, not app/src/main.

Validate In Rockxy

1. Start Rockxy and keep capture running.
2. Open Developer Setup Hub > Flutter.
3. Pick the same runtime host shown in this sample.
4. Copy the active Rockxy proxy port into the sample app.
5. Run Known-good app startup.
6. Confirm Rockxy captures the request.
7. Filter by the displayed X-Rockxy-Lab-Run-Id.

Rockxy validation confirms that the request reached Rockxy through the proxy. It does not prove which device, simulator, emulator, Dart isolate, app, or process emitted the traffic.

Troubleshooting

Connection refused on 127.0.0.1

If the app shows an error like:

Rockxy proxy is not reachable at 127.0.0.1:<copied Rockxy port>.

use the Rockxy proxy is not reachable at ... line as the attempted proxy endpoint. Raw Dart SocketException details can include an OS-assigned local socket port, so do not copy that raw port into the Rockxy port field.

When Proxy through Rockxy is enabled, this usually means the Rockxy proxy is not listening on the port entered in the sample app.

Check these in order:

1. Start capture in Rockxy.
2. Copy the active Rockxy port from the Rockxy toolbar.
3. Paste that value into the sample app's Rockxy port field.
4. Keep the runtime set to iOS Simulator / macOS desktop when running on macOS.
5. Keep the local demo API running in a separate terminal:

fvm dart run tool/rockxy_demo_api.dart --port 43210

For the default local demo, Rockxy and the sample should use two different ports:

• Rockxy proxy: the active port shown in Rockxy, for example 8888 or 9090.
• Demo API: 43210.

Do not put the demo API port into the Rockxy port field.

No route to host on 10.0.2.2

If the app shows:

Rockxy proxy is not reachable at 10.0.2.2:<copied Rockxy port>.
Raw socket error: No route to host

the sample is probably running on macOS while Android Emulator is selected. 10.0.2.2 only works from inside an Android emulator.

Fix it one of two ways:

1. If you are running the Flutter app on macOS, select iOS Simulator / macOS desktop.
2. If you want to test Android Emulator routing, start an Android emulator and run the app on that emulator with fvm flutter run.