Workspace Execution Security

Understand the trust decisions, permissions, execution limits, and secret-handling rules for workspace tasks, triggers, and custom sanitizers.

The CLI runs trusted workspace code for repository tasks, event triggers, and custom session sanitizers. Review that code and its dependencies before enabling it.

Security notice Workspace TypeScript is trusted local code

Ansight process controls are not an operating-system sandbox. A module and anything it imports run with the filesystem, process, and network permissions of the user running the host or CLI. Review code before running a task, connecting triggers, or selecting a custom sanitizer.

When workspace code runs

Task and trigger discovery reads the static descriptor without executing the module. A valid descriptor does not establish that the module is safe to run.

When the CLI runs a module, its initialization code and imported dependencies also execute. Review those alongside the task, trigger, or sanitizer function. Use console.log, console.info, or console.debug for diagnostics; do not write directly to process.stdout.

Module	Execution scope	Starts when
Task	Fresh module state for each run	A person, agent, test runner, local player, or CLI invokes the task.
Trigger	Fresh module state for each attempt, including retries	A connected trigger matches an App ID, event kind, and every condition.
Sanitizer	One export or share operation; item handlers run in order	An export or share explicitly selects the custom sanitizer.

The CLI stops timed-out or cancelled work. Stopping a run does not undo file writes, network calls, or other effects that already completed.

Reduced environment

Workspace code receives a reduced environment with the values needed to locate tools and temporary storage. Tool lookup still uses the configured PATH.

Arbitrary parent variables—including API keys and application secrets—are not copied into the child environment. Test-secret values resolved from secure storage or an explicitly declared environment-variable alias are not injected into workspace runs. Hosted execution credentials are resolved by Ansight and are never copied into the workspace child process.

This is secret minimization, not isolation. The module still runs as the same OS user. It can use operating-system APIs, read accessible files by path, open network connections, and start programs it can locate. Inheriting PATH also means executable resolution follows the host’s current path configuration.

Ansight capability boundaries

The CLI restricts which Ansight operations workspace code can request:

Task host APIs are pinned to the selected sessionId; caller-supplied target overrides are removed.
Standard task host methods are allow-listed by the generated API contract.
ansight.tasks can discover and run tasks only from the caller’s exact repository and App ID, against the same live session. Recursive cycles are rejected and call chains are limited to eight task execution levels.
Extra ansight.callTool names must be declared in task.hostTools and must exist in the active task registry.
App methods remain pinned to the selected live session and are validated against the app’s published tool catalog, argument schema, grants, and tool guard.
A trigger can return no action or one app-tool action. Version 2 also permits one host screenshot, sandbox file capture, or annotation action. It cannot dispatch arbitrary host tools or a sequence of actions through this API.
Version 2 task and trigger requirements are checked against the selected session. SDK app-tool calls are refused when there is no connected provider; external file access remains limited to the selected app’s sandbox roots.
A sanitizer receives the current evidence item and supported helper data; returned content must be an object or null.

These rules constrain calls through Ansight. They do not prevent direct filesystem, process, package, or network access.

Runtime bounds

Control	Tasks	Triggers	Custom sanitizers
Module size	1 MiB	1 MiB	TypeScript module required; export processing remains bounded by archive controls
Module startup	5 seconds	5 seconds	5 seconds
Function time	1–300 seconds; default 120	10–1,000 ms; default 100 ms	20 seconds per item handler
Separate app-action time	Included in task timeout	1–300 seconds; default 30	Not applicable
Ansight/app/task actions	1–100 per task; default 64. A child call is one parent action and the child has its own budget.	At most one returned action per attempt	Sanitizer helpers only
Retries	Caller-controlled new run	1–5 host-owned attempts	No automatic handler retry
Captured stderr	65,536 characters	65,536 characters	65,536 characters
Structured output	Task output and each tool result are bounded	1,048,576 characters	4 MiB response bound

Trigger admission also uses a bounded host queue and configured concurrency. Limits protect host availability and audit size; they do not make malicious code safe.

Trust gates

Module	Required trust decision
Task	The root repository task must be explicitly invoked. It may transitively invoke other tasks in the same workspace, so review its reachable task calls and imports. Workspace tasks may be exposed to a test agent unless the run uses `--no-workspace-tools`.
Trigger	Link or register a trusted codebase, or explicitly connect its catalog. Linking enables the app’s repository automation connection, which is restored at host startup. CLI hosts enable repository automation by default; `--disable-repository-automations` is an explicit host-wide stop.
Sanitizer	The custom module must be explicitly selected for sanitization, export, or sharing.

Treat changes from forks, pull requests, generated patches, downloaded archives, and dependency updates as untrusted until reviewed. A harmless static descriptor does not prove that the default function, top-level module code, or an imported package is harmless.

Recommended controls

Review the complete module and its local imports before enabling it.
Pin and review dependencies; avoid install hooks and unnecessary packages.
Keep workspace modules small and prefer the typed Ansight/app APIs over shell commands or direct network access.
Run the host and CLI as a non-administrator user with least-privilege filesystem access.
Use a dedicated development account, machine, VM, or OS sandbox when the repository is not fully trusted.
Keep secrets outside the repository and do not load them manually from the user’s home directory inside workspace code.
Inspect task and trigger run history, tool-call audits, and captured stderr after execution.
Disconnect trigger catalogs when automatic reactions are no longer needed.
Prefer the built-in sanitizer for untrusted repositories; custom sanitizer code sees sensitive evidence before it returns the redacted copy.

Runtime setup and diagnosis

Workspace TypeScript requires a supported Node.js installation. Check it with ansight doctor; use --node-path when selecting a specific installation:

ansight host run --node-path /absolute/path/to/node
ansight doctor --json

Use a trusted, maintained Node installation. An executable selected through a modified PATH or explicit --node-path runs with the same authority as the Ansight host.