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 the beta .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, resolved path, a justification explaining the Ansight capability it supports, and brief installInstructions.

Full system-state report

Use --full for a programmatic inventory of the current system:

ansight doctor --full --json
ansight doctor --full --json --output system-report.json

The ansight.system-report/v1 result includes OS and hardware, Ansight versions and install details, dependencies and platform tooling, host configuration, known apps and devices, installed agent executables, and existing Ansight skill versions and checksums. It reads declared skill versions where available and computes SHA-256 over their files. Unknown versions stay unknown; comparison with the current bundled skills is included when a baseline exists.

Each section reports its collection status. Missing tools, offline devices, timeouts and unreadable files remain visible in the result. A generated report returns success even when incomplete: inspect isComplete, sections and findings in scripts. --require applies only to the quick health check.

Full collection reads existing state and runs version/discovery probes. It does not install tools, modify skills, create credential stores, boot devices or upload the report. --output saves JSON; omit --json for a text view on stdout. Inventory covers Ansight-relevant tools and locations rather than every OS package. Desktop agent bundle discovery currently covers macOS; CLI agent discovery also covers Windows and Linux.

Secret metadata is excluded unless explicitly requested:

ansight doctor --full --include-secret-metadata --json

That flag includes Ansight secret aliases, app scopes, recorded revision IDs, update times and configuration status where available. Values and hashes of secret values are never included. Environment secrets have no known revision. Without the flag the section is not-requested, and aliases and counts are not collected. --json, --output and verbosity do not enable secret metadata.

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.

Linux credential setup and unattended hosts

Linux support depends on the host environment, not only the distribution name. A usable Secret Service needs secret-tool, a user D-Bus session, and an accessible vault. ansight config credentials and ordinary doctor verify a temporary store/read/delete operation rather than trusting the presence of the executable. The temporary entry contains random probe data, never account credentials. doctor --full retains its separate, read-only report behavior.

For interactive setup, run:

ansight config credentials

If Secret Service is unavailable, setup asks for an existing externally protected key file. Provision the key separately through your administrator or secret manager: it must contain a base64-encoded 32-byte key, be readable by the host user, and have owner-only Unix permissions (0400 or 0600). Keep it outside the encrypted store directory. Setup does not generate, copy, overwrite, or rotate master keys. A key file’s location alone does not provide external protection; secure its storage and backup separately from the encrypted data.

For a persistent headless VM, use a key source that will remain available after reboot, and configure it explicitly:

ansight config credentials --key-file /protected/ansight/master-key --non-interactive
ansight config get credential-provider
ansight config get secret-key-file
ansight doctor --credentials-only

Only provider and file references are saved in cli-settings.json under the CLI data directory. Terminal commands and the resident host load the same defaults; existing encrypted data must authenticate with the supplied key before setup saves anything. Re-running setup preserves saved references and existing keys. Changing providers or rotating a key requires a deliberate migration, not another setup run. Explicit command options and environment credential sources override saved defaults. Unset ANSIGHT_SECRET_MASTER_KEY before configuring persistent key-file defaults. For CI, environment-supplied keys and systemd credentials remain supported without saving their secret values; use doctor --credentials-only to validate them.

The shell installer accepts --secret-key-file <path> and performs credential setup before account login. It reports binary installation, credential readiness, required checks, authentication, and Android readiness separately. Required failures return a nonzero exit code; --no-setup explicitly installs files and reports readiness without requiring a configured host.

Generated systemd user services read the same saved settings and run a credential check before host startup. The installer also checks credentials in a transient systemd user service before enabling startup. An unlocked desktop vault may not remain available after logout: use an external key for unattended operation. The installer offers systemd user lingering for logout and boot persistence; without it, the service follows the user session. For managed services, an administrator can enable it with loginctl enable-linger <username>. Custom service units are preserved. The host user’s key path must remain accessible independently of .bashrc or an interactive login.

Android VM readiness

Ansight first discovers existing Android installations from explicit overrides, ANDROID_SDK_ROOT / ANDROID_HOME, PATH, and standard user SDK folders. It also looks for SDK roots behind adb, emulator, sdkmanager, or avdmanager on PATH, following executable symlinks. On Linux, additional candidates include /usr/lib/android-sdk, /usr/local/lib/android/sdk, /opt/android-sdk, and /opt/android/sdk. The emulator beside the selected ADB installation takes priority. Discovery does not download packages or modify existing SDKs or AVDs; Doctor validates the discovered tools before reporting readiness.

Choose the intended workflow explicitly:

# Physical device or emulator reachable through ADB; no local KVM/image requirement.
ansight doctor --target android-device

# Emulator running inside this host or VM.
ansight doctor --target android-emulator

The external-target check requires ADB and at least one connected, authorized target. The local-emulator check requires ADB, the emulator executable, an AVD referencing an installed system image, and successful emulator -accel-check. Linux also checks that the current user can open /dev/kvm for reading and writing. A VM may require nested virtualization enabled on its outer host and membership in the kvm group. When acceleration is unavailable, use an external Android target instead.

Pass --android-target android-device or --android-target android-emulator to the shell installer to require that workflow’s checks. These are prerequisite checks: they do not boot an app or prove screenshot capture and input work. Local iOS checks are marked not applicable on Linux; explicitly requiring an unsupported check fails.

Optional setup fallback

Automatic discovery remains the normal path. If components are missing, the optional setup command can provision them on Linux x64:

# Preview existing tools, missing packages, sizes, and licenses without changing files.
ansight setup android --dry-run --json

# Install missing ADB tools, or reuse an existing installation.
ansight setup android

# Add local emulator tools and, only if needed, a baseline AVD.
ansight setup android --target android-emulator

Setup uses an existing SDK when it finds one. --sdk-root <path> selects another SDK or a new destination. The validated SDK path is saved for subsequent CLI and host processes; inspect it with ansight config get android-sdk-root. Explicit ADB options and Android environment settings take precedence over the saved path.

The emulator fallback requires Linux x64, usable KVM, at least 4 GiB RAM, adequate free disk space (at least 8 GiB), and JDK 17 or newer. It checks these prerequisites before package downloads. Existing emulator acceleration is checked before any installation; a newly installed emulator is checked before downloading its system image. Setup reports Java or KVM prerequisites rather than changing system packages, virtualization settings, or group membership.

Missing ADB tools come from Google’s official platform-tools archive. Emulator setup reuses existing sdkmanager / avdmanager tools, or bootstraps command-line tools version 19.0. This compatibility path supports an explicit Android 35 Google APIs x86_64 baseline, named ansight-api35 by default. Use --avd-name <name> to choose another name. An existing valid AVD is reused; existing AVDs are never forced overwritten. Google’s newer Android CLI remains available separately; setup does not install or configure its agent integrations.

Before applying changes, setup shows the packages and download sizes and asks for confirmation and license acceptance. --yes skips only the installation prompt. For unattended setup, review the licenses in the dry-run JSON first, then explicitly accept them:

ansight setup android --target android-emulator --yes --accept-android-licenses

Downloads use Google’s HTTPS repository and its published archive checksums. Bootstrap archives are extracted into staging directories before installation; existing package directories are preserved. Setup validates the resulting tools and reports tool readiness separately from target connectivity. A successful ADB installation does not require a device to be plugged in. Booting an app and testing screenshots/input remain separate authenticated product operations.

The shell installer offers this fallback when an explicitly selected Android workflow is unavailable. --setup-android requests it directly, defaulting to ADB; combine it with --android-target android-emulator for local emulator setup. Use --accept-android-licenses separately for unattended installer runs. Ordinary installation and --yes alone do not silently opt into Android downloads. --setup-android and --no-setup cannot be combined.

Credential setup is also available as ansight setup credentials, an alias of ansight config credentials. Both setup targets work before account login.

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.

Headless device targets

Device-launching commands show native windows by default. Use --headless on the command to skip Simulator.app on iOS or start an Android emulator with -no-window. This does not remove the platform requirements: iOS still needs macOS and full Xcode with a compatible simulator runtime, and Android still needs an installed emulator and AVD. Existing windows are not closed. See headless device launches.

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 or dotnet on PATH. Full Doctor reports query installed SDKs and runtimes when dotnet is available. 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.

For a physical iPhone, supply WebDriverAgent signing to the Ansight host through ANSIGHT_APPIUM_XCODE_TEAM_ID and, when needed, ANSIGHT_APPIUM_XCODE_SIGNING_ID, ANSIGHT_APPIUM_WDA_BUNDLE_ID, or ANSIGHT_APPIUM_XCODE_CONFIG_FILE. Set them before starting the host. The phone must be included in the WDA provisioning profile; an arbitrary self-signed bundle cannot replace Apple developer signing. Doctor confirms that Appium and its driver are available, while a device session verifies WDA signing and launch. See physical iPhone external capture.

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 Execution Security for the process model, environment filtering, timeouts, output bounds, and trust gates.