System Requirements and Dependencies

Ansight can run with a small baseline installation. Extra tools are needed only for the features that use them. ansight doctor inspects the current machine and reports that distinction directly:

The distributed CLI is self-contained. Running ansight does not require a system .NET runtime, DOTNET_ROOT, or dotnet on PATH. The .NET SDK and diagnostic tools are optional dependencies used only by .NET profiling workflows. On Linux, self-contained still relies on the operating system’s normal native runtime libraries, including glibc, ICU, OpenSSL, and zlib. Extremely minimal container images may omit them.

For a minimal Linux container, use Microsoft’s .NET runtime-dependencies image as the base; it contains native prerequisites but not the .NET runtime:

FROM mcr.microsoft.com/dotnet/runtime-deps:10.0
COPY ansight /usr/local/bin/ansight
RUN chmod +x /usr/local/bin/ansight && ansight --version

Add the Android SDK, ADB/emulator, Node.js, Appium, and the required Appium driver to that image only when the runner needs Android UI automation.

ansight doctor
ansight doctor --json

Use the text output for setup. Use --json in scripts or support bundles; its versioned ansight.doctor/v1 result includes every check, whether it is required, its status, message, and resolved path.

Baseline requirements

These checks must pass for Doctor to report a healthy host.

The default credential provider is the macOS Keychain, Linux Secret Service, or Windows DPAPI where available. A headless machine without an OS vault must use the protected file store with a master key supplied through a configured key file, a systemd credential, or ANSIGHT_SECRET_MASTER_KEY. Do not keep the key beside the encrypted store or grant group/other access to it on Unix.

Feature-specific dependencies

Missing optional tools produce an amber result. Ansight still works, but the corresponding feature is unavailable or reduced. The order below reflects how much of the general mobile workflow each dependency unlocks. A tool for a platform you do not target is not important for that machine.

Install dependencies in priority order

Android SDK and ADB

The recommended installation is Android Studio. During first-run setup, or later under Tools > SDK Manager > SDK Tools, install Android SDK Platform-Tools. That package supplies adb. Note the Android SDK location shown by SDK Manager.

For a command-line-only Android SDK that already has sdkmanager, install the same component with:

sdkmanager "platform-tools"

Add the SDK’s platform-tools directory to PATH, set ANSIGHT_ADB_PATH to the SDK or adb executable, or pass its location directly:

adb version
adb devices
ansight doctor --adb-path /absolute/path/to/android-sdk

Expected default SDK and ADB paths:

Doctor checks an explicit --adb-path or ANSIGHT_ADB_PATH first, followed by ANDROID_SDK_ROOT, ANDROID_HOME, PATH, and then these conventional roots. An explicit value may point to the executable, platform-tools, or the SDK root.

See Google’s SDK Manager guide and sdkmanager reference for headless installations.

Full Xcode installation

Install Xcode from the Mac App Store or the Apple Developer downloads site, then launch it once to finish component installation and accept its licence. Ansight needs the full Xcode installation for Simulator and devicectl; the standalone Command Line Tools package is not sufficient for those workflows.

Select the intended Xcode and finish its first-run setup:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
xcodebuild -version
xcrun simctl list devices
xcrun devicectl list devices
ansight doctor --xcode-path /Applications/Xcode.app

If Xcode lives elsewhere, pass its .app path with --xcode-path or set ANSIGHT_XCODE_PATH. See Apple’s command-line tools documentation.

The expected default application path is /Applications/Xcode.app, which normalizes to /Applications/Xcode.app/Contents/Developer. Ansight invokes /usr/bin/xcrun; Simulator tooling normally resolves to /Applications/Xcode.app/Contents/Developer/usr/bin/simctl, while physical device commands resolve through xcrun devicectl. Doctor also honors DEVELOPER_DIR, the directory selected by /usr/bin/xcode-select -p, /Applications/Xcode-beta.app, and other /Applications/Xcode*.app installs.

Android Emulator

In Android Studio, open SDK Manager > SDK Tools, install Android Emulator, then open Device Manager and create an Android Virtual Device with a system image suitable for the app. This is the simplest way to install all related pieces together.

With a configured command-line SDK, install the emulator package and confirm that at least one AVD exists:

sdkmanager "emulator"
emulator -version
emulator -list-avds

Creating an AVD also requires a system image. Follow Google’s virtual-device guide to choose and install one.

The expected executable is <Android SDK>/emulator/emulator on macOS and Linux, or <Android SDK>\emulator\emulator.exe on Windows. With the conventional SDK roots above, that is:

• macOS: ~/Library/Android/sdk/emulator/emulator
• Linux: ~/Android/Sdk/emulator/emulator
• Windows: %LOCALAPPDATA%\Android\Sdk\emulator\emulator.exe

Ansight first derives the SDK root from the resolved platform-tools/adb[.exe], then checks ANDROID_SDK_ROOT, ANDROID_HOME, PATH, and the conventional platform roots.

Node.js

Install a supported LTS release from the official Node.js download page. Use the installer for the current OS, or an existing version manager that makes the selected node executable visible to the host process.

node --version
npm --version
ansight doctor

Doctor checks PATH. When starting the host, --node-path /absolute/path/to/node selects a specific runtime for trusted workspace modules.

There is no separate fixed Doctor path: Doctor expects an executable named node on PATH. Common installation paths are /opt/homebrew/bin/node on Apple Silicon Homebrew, /usr/local/bin/node on Intel Homebrew, /usr/bin/node for Linux system packages, and %ProgramFiles%\nodejs\node.exe on Windows. Version managers use their own per-user path and must expose it to the shell or service that starts Ansight. The host also accepts ANSIGHT_NODE_PATH or --node-path for an exact executable.

SkiaSharp native runtime

The supported SkiaSharp native library is bundled with the platform-specific Ansight CLI distribution; there is no separate global package to install. A failure normally means the CLI archive is incomplete or its OS/CPU architecture does not match the machine.

Reinstall the correct Ansight CLI build, then verify it:

ansight doctor

There is no external SkiaSharp installation path to configure. Under the standard macOS/Linux installer, the active CLI payload is ~/.local/share/ansight/cli/versions/<version>-<build>-<rid>/; macOS keeps libSkiaSharp.dylib beside ansight in that directory. The Linux and Windows self-contained executables carry their native asset in the CLI bundle and the .NET runtime manages its extraction. On Windows, the versioned payload root is %LOCALAPPDATA%\Ansight\cli-install\versions\<version>-<build>-<rid>\.

Do not install a random libSkiaSharp beside the executable. If a correctly matched, freshly installed CLI still reports native.skia as unavailable, include ansight doctor --json output in a support report.

Tesseract OCR

Install the executable for the current platform:

# macOS with Homebrew
brew install tesseract

# Debian or Ubuntu
sudo apt update
sudo apt install tesseract-ocr

# Windows with WinGet
winget install UB-Mannheim.TesseractOCR

Then restart the shell and verify:

tesseract --version
ansight doctor

If it is intentionally outside PATH, set ANSIGHT_TESSERACT_PATH to the executable. See the Tesseract installation guide.

Doctor otherwise expects tesseract (tesseract.exe on Windows) on PATH. Typical paths are /opt/homebrew/bin/tesseract on Apple Silicon Homebrew, /usr/local/bin/tesseract on Intel Homebrew, /usr/bin/tesseract for Linux packages, and C:\Program Files\Tesseract-OCR\tesseract.exe for the common Windows installer. If the Windows installer does not add that directory to PATH, point ANSIGHT_TESSERACT_PATH at the executable explicitly.

scrcpy and its matching server

Install scrcpy as one complete distribution so the client executable and scrcpy-server remain the same version:

# macOS with Homebrew
brew install scrcpy

# Windows with WinGet
winget install --exact Genymobile.scrcpy

For Linux, use the current package or static archive described in the official scrcpy Linux guide. Avoid copying only the executable from another installation.

scrcpy --version
ansight doctor

Doctor finds the server beside standard package-manager installations. Set SCRCPY_SERVER_PATH only when using a custom layout, and point it to the server from the same release as the executable. The official scrcpy repository is the authoritative download source.

For the executable, Doctor checks PATH, then the common macOS Homebrew paths /opt/homebrew/bin/scrcpy and /usr/local/bin/scrcpy. Linux packages normally install /usr/bin/scrcpy; Windows package managers must expose scrcpy.exe on PATH.

For the matching server, Ansight first checks SCRCPY_SERVER_PATH, then <prefix>/share/scrcpy/scrcpy-server relative to the resolved executable. It also checks these exact conventional paths:

• /opt/homebrew/share/scrcpy/scrcpy-server
• /usr/local/share/scrcpy/scrcpy-server
• /usr/share/scrcpy/scrcpy-server

On Windows or a portable/custom archive, set SCRCPY_SERVER_PATH when the package layout does not match the <prefix>/share/scrcpy convention.

.NET SDK

The self-contained Ansight CLI does not require a .NET SDK, does not invoke dotnet, and does not require dotnet on PATH. Build your .app, .apk, or .ipa outside Ansight. You may still use an SDK outside Ansight to produce the artifact or to install the diagnostic tools below.

dotnet-trace

Install dotnet-trace using your preferred .NET tool installation environment:

dotnet tool install --global dotnet-trace
dotnet-trace --version
ansight doctor

If the command is not found after installation, restart the shell and make sure the .NET global-tools directory is on PATH: $HOME/.dotnet/tools on macOS and Linux, or %USERPROFILE%\.dotnet\tools on Windows. See Microsoft’s dotnet-trace documentation.

The expected executable is $HOME/.dotnet/tools/dotnet-trace on macOS/Linux or %USERPROFILE%\.dotnet\tools\dotnet-trace.exe on Windows. Doctor resolves the command from PATH; there is no separate Ansight path override.

dotnet-dsrouter

Install dotnet-dsrouter when profiling sandboxed .NET mobile processes:

dotnet tool install --global dotnet-dsrouter
dotnet-dsrouter --version
ansight doctor

It uses the same global-tools PATH rules as dotnet-trace. See Microsoft’s dotnet-dsrouter documentation.

The expected executable is $HOME/.dotnet/tools/dotnet-dsrouter on macOS/Linux or %USERPROFILE%\.dotnet\tools\dotnet-dsrouter.exe on Windows. Doctor resolves the command from PATH; there is no separate Ansight path override.

Appium CLI and XCUITest driver

This dependency is only for physical-iOS input. Install Node.js first, then install Appium through npm and add the XCUITest driver:

npm install --global appium
appium driver install xcuitest
appium --version
appium driver list --installed
ansight doctor

Follow the Appium installation guide and XCUITest driver installation guide for WebDriverAgent signing, Developer Mode, and device trust.

Doctor expects appium (appium.cmd or appium.exe on Windows) on PATH. Its exact path is npm-prefix dependent: common global locations are /usr/local/bin/appium, a version-manager-specific bin/appium, and %APPDATA%\npm\appium.cmd. Appium manages installed extensions beneath its own home, normally ~/.appium; Ansight does not infer or open the driver directory. Instead, it runs appium driver list --installed --json and requires an installed xcuitest driver.

Running Appium server

Installing Appium does not start it. Open a persistent terminal and run:

appium

Leave that process running while using physical-iOS input. In another terminal, verify that Doctor can reach it:

ansight doctor

The default endpoint is http://127.0.0.1:4723/. If Appium listens elsewhere, set ANSIGHT_APPIUM_SERVER_URL to its absolute HTTP or HTTPS URL before starting Ansight or running Doctor.

This dependency has no filesystem path. The expected default network location is http://127.0.0.1:4723/, and Doctor probes its /status endpoint. When the server uses a base path, include it in ANSIGHT_APPIUM_SERVER_URL, for example http://127.0.0.1:4723/wd/hub.

Read the traffic light

An amber result is normal when the machine does not target every platform. For example, a Linux automation host can be healthy without Apple device tooling, and an iOS-only developer does not need the Android SDK.

Diagnose a non-default host

Use the same paths and credential configuration that the real host will use:

ansight doctor \
  --data-dir /path/to/ansight-data \
  --secret-store-file /protected/secrets.json \
  --secret-key-file /protected/ansight.key \
  --adb-path /path/to/android-sdk \
  --xcode-path /Applications/Xcode.app

The resolved paths appear in Doctor output. If a host is started by a service, run Doctor in that service’s user and environment: interactive shells often have a different PATH, credential vault, and systemd credential directory.

Security note for Node.js

Node.js repository modules run as the current OS user and are not an operating system sandbox. Only enable modules from repositories you trust. See Workspace Node.js Security for the process model, environment filtering, timeouts, output bounds, and trust gates.