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

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

WorksDoes not work
Chat, Ask mode and tab completionWriting or editing files: DENIED: ... is disabled in an untrusted folder.
Reading, listing and searching filesRunning commands with run_terminal_command
Language-server toolsWriting 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 folderThe project's own rules, rule files, skills, commands, agents, hooks and connectors: none are loaded
Web searchThe 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.

  1. Click Restricted Mode in the status bar, or run Workspaces: Manage Workspace Trust from the command palette.
  2. Choose Trust. You can trust just this folder or its parent folder, so everything you clone there is trusted.
  3. 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 itTrusted 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 -pAlways: you chose the folder, and --permissions decides what the run may do.
astracode-agent reviewOnly 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

← Working across several repositories Connectors (MCP servers) →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference