Security

Ansight is a privileged development surface. It can expose live app state, screenshots, logs, files, databases, preferences, secure storage, reflection, and app-specific tools to the local host player and connected agents.

SDK production-safety quick starts

Ansight is for development builds only. Use the guides below to keep the SDK and its tools out of your production app.

SDK	Production boundary	Guides
React Native	Guard startup with __DEV__, set toolGuard to "disabled" otherwise, and use a development-only native target when the package must be absent from production.	Setup · Security
iOS	Keep imports and initialization behind #if DEBUG, link Ansight only to a development target, and never enable ANSIGHT_ALLOW_REMOTE_TOOLS in release builds.	Setup · Security
Android	Use debugImplementation and src/debug for Ansight dependencies and startup code so the release variant does not resolve or compile them.	Setup · Security
Flutter	Guard startup with kDebugMode or an explicit development flavor, and use a separate development target or package graph when the native plugin must be absent.	Setup · Security
.NET / MAUI	Use conditional Debug PackageReference items and #if DEBUG initialization; protected builds must set AnsightRemoteToolsPolicy=Disallowed.	Setup · Security
Capacitor	Keep Ansight plugin wiring in a development-only native target or project, and guard JavaScript initialization and tool access with the app’s developer-build flag.	Setup · Security

Build the production version in CI and check that the finished app does not contain any Ansight packages. Keep remote tools disabled outside development.

Host and network access

The resident host exposes different surfaces with different access boundaries:

Do not forward SDK or player ports to the internet or put the local player behind a public reverse proxy. Restrict SDK listeners to the trusted devices that need them using your host firewall and development network. Local capture does not require account sign-in.

Use ansight host run --no-serve when the browser player is unnecessary. Check optional remote access with ansight companion access status; turn it off with ansight companion access disable. Prefer session-only companion access when persistent access is unnecessary. See CLI Commands.

Agent skill disclosure

Review the complete skill source directory before installing agent skills. It lists instruction files, agent metadata, scripts, and supporting assets with SHA-256 hashes. The installation disclosure explains the installed directories, on-demand instructions, release-specific manifests, and how to verify actual installed copies. Hashes detect differences; they do not prevent prompt injection or establish that instructions are safe.

Workspace

Workspace tasks, triggers, and custom sanitizers run as local programs. They have the same access to your computer as the resident host or CLI, including access to files, processes, and the network. Ansight limits their run time and output, but it does not isolate them in a security sandbox.

Only run workspace code you trust. Review each module and its imports before using it, especially when it comes from another repository or team.

Linking or registering a codebase enables its repository automation connection, which is restored when the host starts. Connected triggers can execute in response to app events without another manual invocation. Review trigger modules and dependencies before linking a workspace, and review changes before reusing it. Start the host with --disable-repository-automations to disable repository triggers for that host run. Root tasks still require invocation but may call other tasks in the same workspace, and a custom sanitizer runs when explicitly selected.

The Node environment omits arbitrary inherited secrets, but modules retain the host user’s filesystem, process, and network access. Task tool allow-lists, timeouts, and output limits do not restrict direct Node access to those resources. A test agent may invoke workspace tasks unless the test uses --no-workspace-tools. See Workspace security for the full security model.

Enrollment model

Enrollment registers an app installation with the host. The SDK stores its installation ID and reconnect state in app-private storage. There are three enrollment paths:

These ceilings do not bypass the SDK’s tool guard. Keep unattended provisioning disabled outside trusted test builds, and do not log its bearer payload. See App Setup and Pairing and Tests.

Host addresses are normally discovered automatically. Use ansight pairing issue <app-id> --qr --host-address <LAN-IP> when an explicit reachable address is needed. Enrollment does not require bundled connection files, certificates, or signing keys in the app.

Credentials and expiry

An invitation is one-use for registration. The same bearer secret is retained as the registered installation’s reconnect credential; consumption does not rotate or invalidate it. Treat QR images, pairing codes, generated .ans.json invite files, and stored enrollment state as sensitive for the lifetime of the associated registration. Do not commit them or include them in screenshots, tickets, or logs. If a consumed invite leaks, revoke its registration as well.

Invitation expiry and registration expiry are separate:

• A generic, any-app invite lasts at most 10 minutes.
• An app-specific invite lasts at most 24 hours. Use --duration 15m, for example, to shorten the requested lifetime.
• The requested duration also sets the reconnect grant lifetime, capped at 90 days; the default requested duration is one calendar month.
• Automatic local registrations last 90 days and can be renewed on a later local connection after expiry. Their expiry is not a permanent opt-out from automatic local enrollment.

An expired or consumed QR cannot register another installation, but an existing registration can reconnect until its own grant expires or is revoked.

Revoke and disconnect

For an invite-backed registration, list the invite and revoke it through the host. Revocation removes the invite and its associated reconnect grants:

ansight pairing list --json
ansight pairing revoke <invite-id>
ansight session list --connected --json
ansight session disconnect <session-id>

Revoking a grant or reaching its expiry does not close an already connected WebSocket session. Disconnect each affected session separately; use ansight host stop when all host connections must stop. Disconnecting alone does not revoke a valid reconnect credential. Team-synced invitations must be revoked through the team portal.

Automatic local enrollment has no invitation to revoke with pairing revoke. Disable Ansight initialization in the local app or stop the host when that connection should no longer be available. Clearing app data alone does not prevent a local app from enrolling again.

Tool policy model

Remote tools can disclose app data and change app behavior. A policy describes the authority required by a tool, not the sensitivity of every value it returns.

Policies are ordered (read < write < critical). A guard or enrollment grant stores one maximum policy and automatically includes lower policies. Execution must satisfy both the host grant and the SDK guard, as well as the tool’s availability. Allowing a tool in the app does not raise the host grant ceiling.

Keep a deny-all guard outside developer builds. Start at read and broaden the maximum only when the current debugging task needs mutation or a critical operation.

SDK tool policies do not sandbox workspace code or restrict independent host capabilities such as native device control. A deny-all remote-tool guard also does not disable ordinary screenshot, log, or telemetry capture; configure capture separately or omit SDK initialization entirely.

Local data and outbound processing

Normal session capture writes evidence to the developer machine. Viewing that capture locally does not upload the capture. Local JSON, screenshots, artifacts, and the Trends SQLite database are ordinary files, not an encrypted vault. They rely on OS permissions and any full-disk encryption you enable. Credential storage is separate: account and test secrets use the OS credential vault or a configured encrypted store; declared test-secret aliases can also resolve from environment variables.

Use test accounts and the smallest useful dataset. App screens, logs, network metadata, crash reports, files, and tool results may contain personal data or credentials even when they come from a development build.

CLI and local-player activity events are sent to PostHog. Detailed tracking is enabled by default. Inspect analytics with ansight analytics status and disable detailed tracking with ansight analytics detailed disable. Disabling detailed tracking does not disable daily activity or CLI install/update events. See CLI data and security and Data, Privacy, and Analysis for storage locations and outbound workflows.

Sharing and sanitization

Cloud product uploads require sign-in, an exact registered App ID, and the relevant organisation entitlement. ansight session share uploads a raw capture by default, with team as the default audience. Select sanitization explicitly:

ansight session sanitize <session-id> session.safe.zip
ansight session share <session-id> --team-id <team-id> --sanitize

Review the sanitized ZIP before sharing. Use a completed capture so new evidence cannot arrive between review and upload; the share command applies the selected policy to the source capture again. The CLI also supports --access authenticated and --access public (--public is shorthand). Choose team for team-restricted evidence; do not assume that requiring authentication restricts access to your team. Public sharing is intended for evidence that may be viewed without sign-in. Confirm the destination and audience before upload, including whether native device logs should be included.

Sanitization writes a filtered copy and leaves the original local capture unchanged. Built-in PII matching and screenshot OCR can miss sensitive values; binary artifacts require an explicit keep/remove decision. Inspect screenshots, trees, logs, network metadata, annotations, and artifacts, and omit anything that cannot be safely reviewed.

A custom --sanitizer <module.ts> replaces the built-in export policy. It sees unredacted evidence and runs as trusted local code with the host user’s access. Review its imports and output before relying on it. See Sanitizers and Exports and Handoff.

Retention and deletion

Manage each retained copy separately. ansight session delete <session-id> removes a local capture; it does not remove independent Trends history, exported ZIPs, cloud copies, or copies already downloaded by another person. Compaction and archiving retain data. Pinned captures are protected from cache deletion, so review them as part of retention work.

Use ansight session cache plan to preview local cleanup. Set separate retention and backup handling for Trends history, host logs, app-private SDK/crash data, exports, and cloud evidence. Removing a cloud copy cannot recall a recipient’s downloaded copy. See Retention, backup, and deletion.

Use ansight cloud session delete <cloud-session-id> to delete a shared cloud session when you have permission. Cloud session IDs and local session IDs are different identifiers; confirm the cloud record with ansight cloud session list before deletion. This action does not establish a backup-erasure deadline.

Cloud assurances and security reports

Before sending sensitive data to cloud features or a model provider, confirm the applicable storage regions, subprocessors, transport and at-rest encryption, key ownership, provider retention and training terms, staff/support access, backup deletion periods, and incident notification arrangements. The local security controls described here do not establish those service commitments or claim a compliance certification.

Use the existing Ansight contact address to request cloud security information or arrange a private vulnerability-reporting channel. Start with the affected version, platform, and a non-sensitive summary of the issue. Do not put enrollment credentials, customer captures, or other secrets in public issues or an initial contact message.

Checklist

• Run the Ansight host and the app on a trusted local network.
• Review local enrollment, companion access, and connected workspace triggers.
• Keep invite lifetimes short and protect reconnect credentials after enrollment.
• Scan only QRs displayed by the local player or CLI host you intend to use.
• Omit the SDK from production builds and deny tools in protected variants.
• Prefer a read SDK guard and grant when mutation is unnecessary.
• Review and sanitize evidence before export, model use, or cloud sharing.
• Check the sharing audience and retain only the copies you need.
• Revoke stale invite-backed registrations and disconnect their live sessions.
• Review the platform-specific privacy prompts before enabling QR scanning.