xRay: a Flutter debugging tool for teams

A tester finds a bug on their phone. The screen shows the wrong price. Was it the API, a value cached in SharedPreferences, or our own code? The answer is on that phone, in a request nobody saw and a log nobody kept. So a developer plugs in a cable, runs the app from their IDE and tries to make it happen again.

That's why we built xRay at impaktfull: a Flutter debugging tool for developers, QA and product people. Add one package to your app and the xRay desktop app shows every network call, log, stored value and file of your debug build, live, on one timeline. On macOS, Windows and Linux. I showed it in a livestream; this is the written version.

What xRay shows you

  • Network calls. A Flutter network inspector for Dio, http and HttpClient, with headers, bodies, sizes and timing. GraphQL operations by name (also the errors that come back with a 200), WebSocket messages, and protobuf and gRPC-web decoded with your own .proto files. Serverpod calls too.
  • Logs. A Flutter log viewer with the level, the logger, the error and the stack trace, searchable and filterable.
  • Storage you can edit. View and edit SharedPreferences and secure storage while the app runs: flip a value and see what the app does.
  • Databases and files. SQLite through sqflite or drift and Hive boxes, with SQL, read-only unless you allow writes. Browse, preview and save the app's documents and caches.
  • One timeline. Calls, logs and storage changes on one axis, so you see what happened in what order.
  • Device actions. Switch appearance, locale, text scale and animations, open deep links, simulate a push, toggle feature flags.
  • Share a session. Export everything as a .xray file or HAR, or one call as cURL or Markdown. The bug report comes with the evidence.

Several apps and devices can be open side by side, there's a ⌘K command menu, and the app speaks 18 languages, because the tester who finds the bug isn't always a developer.

Set up xRay in three steps

  1. Install the desktop app from xrayinspector.dev and sign in.
  2. Add the package to your Flutter app and start the inspector in debug builds.
  3. Run the app. xRay finds it on your network; enter the pairing code the app prints, once.
dependencies:
  xray_inspector: ^0.1.0
  xray_network_dio_interceptor: ^0.1.0 # if you use Dio
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:xray_inspector/xray_inspector.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    final networkInspector = XRayNetworkInspector(enableHttpOverride: true);
    final logInspector = XRayLogInspector();
    await XRayInspectorServer(
      config: XRayInspectorServerConfig(
        deviceName: () => 'Pixel 8',
        appName: () => 'Shop',
        inspectors: [networkInspector, logInspector],
      ),
    ).start();
  }
  runApp(const MyApp());
}

All xRay packages share one version. There are inspectors for Dio, Serverpod, SharedPreferences, secure storage, sqflite, drift, Hive and device actions on pub.dev; the quick start walks through all of them.

xRay and Flutter DevTools

xRay doesn't replace Flutter DevTools; most teams use both. DevTools is for the widget tree, performance, memory and the debugger. xRay is for the data your app sends, logs and stores. A screen renders wrong or drops frames: DevTools. A screen shows the wrong data, a request fails, or a tester found a bug on their phone: xRay.

The difference that matters most to us: DevTools needs a debugger session from flutter run or an IDE, xRay connects over the local network. No cable, no IDE, so a tester can use it on any debug build. And DevTools has no view of secure storage, no shared timeline and no session to hand to a teammate. The full comparison is on xRay as a Flutter DevTools alternative.

Safe by default

  • Debug builds only. kReleaseMode is a compile-time constant: in release builds the compiler drops the call and nothing from xRay runs. Profile builds don't start the inspector either. A protected internal build can opt in, but only with a password or trusted desktops.
  • No cloud. The inspector runs inside your app on your local network and the desktop app talks to it directly. Captured data only lives in the app's memory, and xRay sends no telemetry.
  • Encrypted and paired. Traffic is encrypted (X25519 and ChaCha20-Poly1305) and a desktop needs the pairing code, a team password or a trusted key.
  • Secrets stay hidden. Tokens and cookies are masked before they're stored, and redaction rules apply to every export.

Your AI assistant can look too

xRay has a built-in MCP server. Switch it on and Claude Code, Cursor, VS Code and other assistants on your computer can read what xRay sees: the failing call, the logs around it, the stored values. With actions allowed, they can also open a deep link, set a feature flag or take a screenshot to check their own fix. It listens on your computer only, and redaction applies to everything an assistant reads.

The talk: see inside your Flutter app

In the livestream I showed xRay on a real app: the network calls, logs and stored values in one tool, and the internal builds where Flutter's own debugging tools are gone. The links are with the other talks.

Try xRay

xRay is free during the alpha: request access on xrayinspector.dev. The documentation has the setup per platform, the code is on GitHub, and questions are welcome on Discord.

Written by

Koen Van Looveren

Flutter developer, founder of impaktfull and Wizzi, and one of the organisers of Flutter Belgium.