Connections and security

Open Settings → Connections. The app calls its two connection modes Basic and Secure; there is no separate “Advanced” mode. Both support the same inspectors. They differ in transport security and setup.

	Basic (default)	Secure (optional)
Transport	Unencrypted ws://	Verified TLS over wss://
Access key	Not required	Required
Certificate setup	None	Trust the dedicated Device CA
Default reachability	This Mac only	Reachable device listener, subject to network/firewall access

Local simulators and physical devices

Basic accepts loopback connections by default. Simulators/emulators on this Mac and devices using local port forwarding can connect without enabling network access. The usual direct addresses are 127.0.0.1 for iOS Simulator and 10.0.2.2 for Android Emulator.

For a physical phone over Wi-Fi or Ethernet in Basic mode:

1. Enable Connect devices over Wi-Fi or Ethernet in Connections.
2. Put the Mac and device on the same reachable, trusted network.
3. Use native discovery or specify the Mac’s hostname/LAN address in the SDK.
4. Allow the app’s local-network permission and relevant firewall access.

This toggle also enables Bonjour advertising. It is not a master connection switch: local connections work while it is off. Basic provides no encryption or access-key authentication, so enabling network access allows other reachable clients to connect. Do not expose it to an untrusted network or the internet.

The SDK listener defaults to 49152. The HTTP/HTTPS proxy is separate, defaults to 49153, and is configured under Settings → Proxy.

Local .NET and Node.js servers also connect through 127.0.0.1 without enabling network access. Docker Desktop for Mac uses host.docker.internal instead and needs network access enabled. The server opens an outgoing connection; there is no inbound debugger API to expose. See .NET setup or Node.js setup.

Android USB forwarding (optional)

adb reverse lets an Android app reach Tracebeam through its USB debugging connection. It is an alternative to Wi-Fi, not a requirement for the Android Emulator quick start: the emulator already reaches the Mac through 10.0.2.2.

1. Install Android SDK Platform-Tools if adb is not available. Enable USB debugging on the phone, connect it by USB, and approve the Mac’s debugging prompt.

2. Leave Tracebeam in Basic. Connect devices over Wi-Fi or Ethernet can remain off.

3. Confirm the phone appears as device (not unauthorized or offline), then forward the listener port:

   adb devices
   adb reverse tcp:49152 tcp:49152

4. Set the adapter host to 127.0.0.1 and port to 49152, then restart/reload the app. See the React Native or Flutter example. An explicit host bypasses discovery.

The first port is on Android; the second is on your Mac. If you changed Tracebeam’s listener port, use that port in both positions and in the adapter configuration. Forwarding Metro’s port (usually 8081) does not forward Tracebeam’s separate listener.

With multiple devices/emulators attached, select the phone’s serial from adb devices:

adb -s YOUR_DEVICE_SERIAL reverse tcp:49152 tcp:49152

Check or remove the mapping with:

adb reverse --list
adb reverse --remove tcp:49152

Add -s YOUR_DEVICE_SERIAL to those commands too if multiple devices are attached. Reapply forwarding if it disappears after a reconnect, reboot, or ADB restart. If adb is not on your shell path, use the executable in your Android SDK’s platform-tools directory.

Forwarding changes the connection path, not the adapter’s security mode or Android networking policy. Basic needs no key or certificate, but debug cleartext WebSockets must still be allowed. Secure still requires its normal key and certificate configuration; forwarding does not bypass authentication or TLS checks. Android’s port-forwarding guide.

Secure (optional)

Select Secure, complete the Mac’s Keychain setup, then copy the device access key and export the Device CA Certificate from the same screen. Configure your adapter using the React Native, Flutter, .NET, or Node.js instructions.

The device access key is generated locally and retained for this Mac’s Tracebeam setup; it is not regenerated for every connection. Keep it private and out of source control and production builds. An app-installation ID used to remember devices is a separate identifier, not a credential.

With the installed SDKs, supplying the dedicated CA trusts it only for the debugger socket while preserving chain and hostname verification. The copied React Native connector uses platform trust instead. Use the Mac’s actual .local hostname for physical-device Secure connections over the local network; an arbitrary LAN IP may not match the certificate.

In React Native and Flutter, supplying either accessKey or deviceCACertificate selects Secure. In .NET, explicitly set Connection.Endpoint to wss://, supply AccessKey, and configure DeviceCertificateAuthorityPath unless the runtime already trusts the Device CA. A key is required for authentication. Failed Secure connections never retry as Basic.

Node.js uses url, accessKey, and deviceCertificateAuthorityPath. Supplying a key or CA selects wss:// if no URL is given; Secure requires a key, and an explicit plaintext URL with credentials is rejected.

To return to Basic, select Basic on the Mac and remove the adapter’s key and certificate options. For .NET or an explicit Node.js URL, also change the endpoint back to ws://.

The Device CA is for SDK connections. The Proxy CA is only for HTTPS interception. They are not interchangeable.

Mode changes and Keychain cancellation

Successful mode, network-access, or listener-port changes restart the listener, disconnect devices, and clear live capture. SDKs reconnect using their configured mode and address.

Cancelling or denying Keychain access while activating Secure leaves Basic selected and preserves the existing Basic capture. Select Secure again to retry in the same session. This setup cancellation is different from silently downgrading a failed Secure network connection.

If Keychain access is explicitly denied when restoring Secure at launch, the app saves Basic for the next launch. Other Secure startup errors leave the Secure listener closed and offer Retry Secure Setup.

Troubleshooting

• No device appears: check the SDK is running in development, the Mac listener is active, and mode/port agree. Physical devices need the Mac’s reachable address, unless using Android adb reverse with 127.0.0.1.
• Simulator works, phone does not: check Basic network access, local-network permission, firewall, and whether the network isolates devices.
• .NET server or container does not appear: run in Development and check the endpoint. A local server uses 127.0.0.1; Docker Desktop for Mac uses host.docker.internal and requires local-network connections enabled in Tracebeam. See .NET troubleshooting.
• Node.js server or container does not appear: check NODE_ENV is unset or development and verify the address. Docker Desktop for Mac uses host.docker.internal and requires local-network access enabled. See Node.js troubleshooting.
• TLS failure: use the current Device CA, a hostname covered by it, and a matching access key. Do not install the Proxy CA as a workaround or disable validation. Update and rebuild older SDKs before retrying.
• Secure setup was cancelled: select Secure again in Connections; a restart is not required.
• Reconnect creates a new remembered device: fully rebuild the updated native SDK. Identity survives reconnects and app launches, but resets after uninstall/data clearing or simulator erase. The copied React Native connector has no native persistence.
• Capture is incomplete: inspect Capture Health and SDK diagnostics. A connected indicator does not guarantee every observation was retained.