Troubleshoot SDK Networking

Use the network doctor when the SDK container, Insight UI, DevKit SSH, RTSP, WebRTC video, or workspace sync does not behave as expected.

The doctor command is read-only. It inspects the host route, Docker container state, published ports, Insight port map, firewall state, and selected Linux networking details.

Run a quick check

sima-cli sdk doctor network --devkit <devkit-ip>

If more than one SDK container exists, pass the container name:

sima-cli sdk doctor network --devkit <devkit-ip> --container <container-name>

Collect a support bundle

When you need help from SiMa support, collect a bundle:

sima-cli sdk doctor network --devkit <devkit-ip> --collect

To choose the output location:

sima-cli sdk doctor network --devkit <devkit-ip> --collect --output ~/sima-sdk-network-doctor.tar.gz

The bundle includes sanitized host, Docker, route, firewall, NetworkManager, and Insight port-map diagnostics. It is intended for networking support. Do not manually add SSH keys, Docker credential files, browser cookies, or other secrets to the archive.

Common findings

Finding	Meaning	Recommended action
vpn-route	The route to the DevKit goes through a VPN or tunnel interface.	Disconnect the VPN or adjust routing so the DevKit uses the physical DevKit-facing interface.
missing-simasdkbridge	The SDK container is running but is not attached to simasdkbridge.	Recreate or restart the SDK with sima-cli sdk setup. Avoid direct VS Code Dev Containers startup for DevKit workflows.
host-network-mode	The SDK container was started with Docker host networking.	Recreate the SDK with sima-cli sdk setup; host networking is not the supported Insight port model.
port-map-mismatch	Docker published ports do not match the generated Insight port map.	Recreate the SDK container so sima-cli can regenerate ports and the Insight configuration together.
stale-port-bindings	A stopped SDK container has saved Docker port bindings that are no longer available.	Remove/recreate the container through sima-cli sdk setup.
nm-shared-iptables-blocking	NetworkManager shared networking rejects SDK bridge traffic before Docker rules are reached.	Run sima-cli sdk network repair --devkit <devkit-ip>; add --persist if the fix must survive reconnects/reboots.
container-devkit-reachability	The SDK container could not confirm SSH or ping reachability to the DevKit.	Confirm the DevKit IP, cable/network path, DevKit SSH service, and host firewall.

DevKit dependency downloads fail

When the DevKit uses the recommended shared-network link, it depends on the host for Internet access. If package installation, dependency downloads, or external service access fail on the DevKit, check:

• The host computer can reach the Internet.
• The host shared-network interface is still active.
• VPN routing is not capturing the DevKit route.
• Linux forwarding/NAT rules are still present if NetworkManager recreated the shared connection.

Run:

sima-cli sdk doctor network --devkit <devkit-ip>

If the doctor reports a NetworkManager shared-network blocking issue, run the repair command shown in the doctor output.

Repair Linux shared-network routing

On Ubuntu/Linux hosts using NetworkManager shared networking, run:

sima-cli sdk network repair --devkit <devkit-ip>

To install the persistent dispatcher hook after applying runtime repair:

sima-cli sdk network repair --devkit <devkit-ip> --persist

The repair is scoped to the SDK bridge and the detected DevKit-facing shared-network path. It does not switch Docker to host networking and does not set the global FORWARD policy to ACCEPT.

Verify after repair

Run the doctor again:

sima-cli sdk doctor network --devkit <devkit-ip>

Then open the Insight URL reported by:

neat --json

If the browser cannot open Insight, verify that the mainUI host port is reachable from the host browser and that the SDK container was started by sima-cli sdk setup.

Insight viewer URL routing

When creating or recreating an SDK container with Insight enabled, SDK setup writes direct to the host-mounted insight-config/url-routing file. This replaces any previous routing declaration, including proxy. No command-line parameter is needed. Insight builds viewer URLs from the browser request host and the published videoUI port instead of treating a local launch hint as a shared proxy origin.

SDK setup does not change launch-url or browser-ice-address. CloudEx DevKit pairing remains separate from browser URL routing. --no-insight and --minimal do not write a routing declaration. Reusing an existing container does not run this creation-time initialization.

Hosted ALB/shared-ingress provisioning must apply its routing override after SDK setup: write the public URL to launch-url and proxy to url-routing, then restart Insight and verify /api/health and /api/viewer-url. Recreating the SDK container resets routing to direct, so the hosted provisioning step must reapply proxy each time. The hosting team owns that integration. CloudEx transport and ALB/nginx rules are configured separately.

For an older local container that returns a viewer URL on Insight's backend port and gets a 404, write direct to /home/docker/.insight-config/url-routing and run insight-admin restart inside that container. Do not apply this local repair to a hosted ALB/proxy environment.