Docs › Workspaces › Workspace trust
Workspace trust
What AstraCode does in a folder you have not trusted, how to trust one in the editor and the CLI, and why it matters.
On this page
- What an untrusted folder can do
- Trust a folder in the editor
- Trust in the CLI
- Trust is not approval
- If something goes wrong
A repository you have just cloned is code someone else wrote. It can contain files aimed at the agent: rules telling it what to run, hooks that run commands, connectors that start programs. So AstraCode does less in a folder until you say you trust it. Reading and answering questions work everywhere; changing things does not.
What an untrusted folder can do
| Works | Does not work |
|---|---|
| Chat, Ask mode and tab completion | Writing or editing files: DENIED: ... is disabled in an untrusted folder. |
| Reading, listing and searching files | Running commands with run_terminal_command |
| Language-server tools | Writing a plan file, or ticking steps in one |
| Read-only commands, after you approve each one with the warning This folder is not trusted, and this runs a command in it. | Connector tools that do not declare themselves read-only |
| Your own connectors, rules, skills, agents and hooks from your home folder | The project's own rules, rule files, skills, commands, agents, hooks and connectors: none are loaded |
| Web search | The codebase index |
A workspace's own values for these settings are also ignored until you trust it: astracode.instructions, astracode.model, astracode.agent.maxSteps, astracode.browser.defaultUrl, astracode.mcp.servers and astracode.mcp.enabled. Your approval setting, astracode.agent.approvalMode, can never be set by a workspace at all.
When the agent is refused in an untrusted folder, it is told to ask you to trust the workspace, and it says so in the chat rather than looking for a way round.
Trust a folder in the editor
The first time you open a folder, the editor asks whether you trust the authors of its files. Choose Yes, I trust the authors for your own code. If you chose no, the window shows Restricted Mode in the status bar.
- Click Restricted Mode in the status bar, or run Workspaces: Manage Workspace Trust from the command palette.
- Choose Trust. You can trust just this folder or its parent folder, so everything you clone there is trusted.
- Send your message again. Rules, skills, hooks and the index load straight away.
To take trust away, open Workspaces: Manage Workspace Trust again and choose Don't Trust, or remove the folder from the trusted list there.
Trust in the CLI
The CLI keeps its own list of trusted folders, as trustedFolders in ~/.config/astracode/settings.json.
| How you run it | Trusted when |
|---|---|
astracode-agent (the full-screen conversation) | You answer Yes, I trust this folder the first time you run it in that folder. No, exit quits. |
astracode-agent -p | Always: you chose the folder, and --permissions decides what the run may do. |
astracode-agent review | Only with --trust, because a pull request from someone else's fork can reach it. |
astracode-agent acp (Zed, JetBrains) | Only with --trust, ASTRACODE_TRUST=1, or a folder already in the trusted list. |
For any of them, --trust trusts the folder for one run and ASTRACODE_TRUST=1 in the environment does the same. Only the first-run question adds a folder to the list for good. An untrusted CLI session starts by saying so: ... is not trusted: the agent will read and answer here but not change files or run commands, followed by which of the project's files were not loaded. More in The conversation and Zed and JetBrains.
Trust is not approval
Trusting a folder lets the agent ask to change things there; it does not stop it asking. Your approval setting still applies, and the actions that always ask still always ask.
If something goes wrong
- DENIED: "write_file" is disabled in an untrusted folder, or the same for another tool: trust the folder as above. In the CLI, rerun with
--trust. - Project rules are ignored in a workspace you have not trusted.: trust the folder to apply them.
- Your project's skills, agents or connectors are missing: they load only once the folder is trusted.
- More on Agent run problems and CLI problems.
← Working across several repositories Connectors (MCP servers) →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems