Diffex is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
Project trust controls whether Diffex loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
Diffex considers a project to have resources that require trust when it finds any of these from the current working directory:
.diffex/settings.json.diffex/extensions,.diffex/skills,.diffex/prompts, or.diffex/themes.diffex/SYSTEM.mdor.diffex/APPEND_SYSTEM.md- project
.agents/skillsin the current directory or an ancestor directory
A bare .diffex directory does not count as a project resource that requires trust.
When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, Diffex follows defaultProjectTrust from global settings. The default value is "ask", which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in ~/.diffex/agent/trust.json, and the closest saved decision on the current or parent path applies before the global default.
Trusting a project allows Diffex to load project resources that require trust, including:
.diffex/settings.json.diffexresources such as extensions, skills, prompt templates, themes, and system prompt files- missing project packages configured through project settings
- project-local extensions and project package-managed extensions
Declining trust skips protected resources. Context files such as AGENTS.override.md, AGENTS.md, and CLAUDE.md are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, Diffex only loads context files, user/global extensions, and CLI -e extensions. User/global and CLI extensions can handle the project_trust event; the first extension that returns a yes/no decision owns the decision.
Non-interactive modes (-p, --mode json, and --mode rpc) do not show a trust prompt. Without an applicable saved trust decision, defaultProjectTrust: "ask" and "never" ignore such resources, while "always" trusts them. Use --approve/-a or --no-approve/-na to override project trust for one run.
Diffex does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the Diffex process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
This is intentional. Diffex is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
Project trust is only an input-loading guard. It prevents a repository from silently changing Diffex's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by Diffex.
For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run Diffex in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
Common patterns are documented in Containerization:
- run the whole Diffex process inside a container/sandbox
- mount only the workspace paths the agent should access
- avoid mounting host
~/.diffex/agentunless the container should access host sessions, settings, and credentials - pass the minimum required API keys or use short-lived credentials
- restrict network access when the task does not need it
- review diffs and outputs before copying results back to trusted systems
If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
Invocation traces, evolution artifacts and failures, candidate history, lifecycle observations, writer receipts, and harness revisions persist beneath the effective agent directory. They can contain session evidence, generated instructions, skill content, paths, and runtime metadata. Evolution model calls may consume provider quota.
Evolved skills are generated instructions and can direct the model to use tools or referenced assets. Structural, provenance, scope, and security validation reduce risk but do not prove semantic safety and are not a sandbox. Retrieval and behavioral evaluation is temporarily skipped when no evaluator is configured, so those candidates have not been checked for retrieval quality, behavior improvement, misapplication, or regressions. Project trust does not sandbox an already selected harness revision.
Review /evolve provenance, draft diffs, validation, whether evaluation ran or was skipped, and the complete generated package before activation. Use /version and rollback controls to select immutable revisions, and use OS or container isolation for unattended work. See Harness Evolution.
To report a security issue, follow the repository Security Policy. Do not open a public issue for security-sensitive reports.
Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how Diffex grants access that the local user did not already have.