# Atlas asks for an external_directory permission on a path outside the project > Approve the external_directory prompt, or approve with `always` to persist the directory glob, or add an allow rule for external_directory scoped to that directory. Atlas pauses for an external_directory permission prompt because assertExternalDirectoryEffect checks containsPath against the instance context and anything outside it triggers ctx.ask with the permission external_directory and a glob pattern for the parent directory, so the fix is to approve the prompt once, approve with `always` to persist the directory glob, or add an allow rule for external_directory scoped to that directory in your config. Rejecting the prompt fails the tool call, which is the intended outcome. Before you approve anything, check the path: a stray absolute path that should have been inside the project is the usual cause, and the real fix there is to correct the path rather than widen the permission. ## Symptom A read, edit, glob, grep, lsp, or apply_patch call on a path outside the project pauses for an external_directory permission prompt, and fails if you reject it. ## Cause assertExternalDirectoryEffect checks containsPath against the instance context. Anything outside it triggers ctx.ask with permission external_directory and a glob pattern for the parent directory, so leaving the workspace is always an explicit decision. ## Fix 1. Look at the path in the prompt first. If the path should have been inside the project, fix the path instead of approving; a stray absolute path is the usual cause. 2. Approve the prompt once if the access is legitimate and one-off. 3. Approve with `always` to persist the directory glob, so Atlas stops asking for that directory on future calls. 4. Or add an allow rule for external_directory scoped to that directory in your Atlas config, which is the durable, reviewable version of the same decision. 5. On Windows, note the path is normalized with FSUtil.normalizePath before the containment check, so separator style is not the reason the prompt appeared. 6. Re-run the tool call and confirm the read, edit, glob, grep, lsp, or apply_patch proceeds without pausing. ## Why does Atlas ask for permission on a path outside the project Atlas asks because assertExternalDirectoryEffect checks containsPath against the instance context, and any path outside it triggers ctx.ask with the permission external_directory. Leaving the workspace is always an explicit decision, so all 6 path tools, read, edit, glob, grep, lsp, and apply_patch, pause at the boundary. The prompt is a workspace boundary, not a failure. Atlas resolves the target path, compares it against the instance context with containsPath, and when the path falls outside, it stops and asks you rather than quietly reaching into your home directory, a sibling repository, or the system. The prompt carries a glob pattern for the parent directory, which is what lets a single approval cover a whole directory instead of one file at a time. Six tools sit behind the same check: read, edit, glob, grep, lsp, and apply_patch. Rejecting the prompt fails the tool call, which is the correct behavior when the access was not intended in the first place. ## How to approve an Atlas external_directory prompt once or forever An Atlas external_directory prompt has 2 approval forms. Approve once and the single tool call proceeds. Approve with `always` and Atlas persists the glob pattern for the parent directory, so later calls under that directory stop pausing. Both routes are decisions you make explicitly, on purpose. Pick the form that matches how often you actually need the access. A one-time approval is right for a single look at a file outside the workspace, such as reading a config from another checkout. Approving with `always` is right when you are working across two directories for a whole session and do not want to answer the same question repeatedly. The persisted unit is the directory glob that Atlas showed you in the prompt, not the individual file, so understand the scope you are granting before you choose `always`. The honest caveat: an `always` approval means Atlas can reach that entire directory tree without asking again, so read the glob in the prompt before you accept it. ## How to add an external_directory allow rule in the Atlas config Add an allow rule for external_directory scoped to 1 specific directory in your Atlas config when the access is permanent and part of how you work. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the rule stops the prompt at the source. A config rule is the durable, reviewable version of an `always` approval, and it has one real advantage: it lives in a file you can read, diff, and reason about later, rather than in an approval you clicked through weeks ago. Scope the rule to the directory you actually need. An external_directory allow with a broad pattern gives Atlas standing access to everything under it, and unlike the interactive prompt, a config rule never surfaces the glob to you again for a second look. Keep the pattern tight, name the directory explicitly, and re-check the rule whenever the surrounding project layout changes. ## When the external_directory prompt means your path is wrong An unexpected Atlas external_directory prompt is often a bug report about the path, not a permissions problem, and 1 stray absolute path is the usual cause. If the file was supposed to live inside the project, fix the path rather than approving access to a directory you never meant to touch. Treat the prompt as a free correctness check. Atlas is telling you, before anything runs, that the target of this read, edit, glob, grep, lsp, or apply_patch call is not inside the workspace. When you expected the file to be inside the project, that mismatch is the actual finding. Common shapes include an absolute path pasted from another machine, a path built from the wrong root, or a relative path that resolved against something other than the instance context. Approving such a prompt hides a real defect and lets the tool operate on the wrong file. Correct the path first, re-run, and the prompt should not appear at all. ## Why the external_directory prompt appears on Windows paths On Windows, Atlas normalizes the path with FSUtil.normalizePath before the containment check runs, so the choice between the 2 separators, backslash and forward slash, is never the reason an external_directory prompt appeared. If Atlas prompts on Windows, the normalized path genuinely resolved outside the instance context. Windows developers reasonably suspect separator handling when a path they believe is inside the project triggers the prompt. Rule that out immediately: FSUtil.normalizePath runs first, and containsPath compares the normalized path against the instance context. A prompt therefore means the path really is outside the workspace once normalized, and the next thing to check is the root the path was built from, not its slashes. Drive letters, paths pointing at another checkout, and paths anchored somewhere above the project root are the realistic candidates. The remedy is the same as everywhere else: correct the path if the target should have been internal, or approve deliberately if the external access is genuinely what you want. ## How to verify the external_directory fix worked Verify the fix by re-running the exact tool call that paused. With a correct external_directory allow rule or a persisted `always` approval, Atlas runs the call without pausing across all 6 path tools: read, edit, glob, grep, lsp, and apply_patch. A repeat prompt means the glob does not cover your path. The signals are easy to read. No prompt and normal tool output means the permission now resolves to allow for that directory. Another prompt means the scope you granted is narrower than the path you are hitting, so compare the glob pattern Atlas is showing you against the actual target path, and widen the rule to the correct parent directory if the access is intended. If you fixed a stray absolute path instead of granting permission, the confirmation is different and better: the call runs with no prompt at all, because the target now falls inside the instance context and assertExternalDirectoryEffect never reaches ctx.ask. ## FAQ ### why does Atlas ask permission to read a file outside my project Atlas checks containsPath against the instance context in assertExternalDirectoryEffect. Any path outside that context triggers ctx.ask with the permission external_directory and a glob for the parent directory, so leaving the workspace is always an explicit decision. ### how do I stop Atlas from asking about external directories Approve the prompt with `always` to persist the directory glob, or add an allow rule for external_directory scoped to that directory in your Atlas config. Keep the scope tight, because both routes grant standing access to the whole directory. ### what happens if I reject the external_directory prompt in Atlas Rejecting the external_directory prompt fails the tool call. Nothing is read, edited, or patched. Rejection is the correct outcome when the path was not supposed to leave the project in the first place. ### which Atlas tools trigger the external_directory permission The read, edit, glob, grep, lsp, and apply_patch tools all pass through assertExternalDirectoryEffect, so any of them can pause for an external_directory prompt when the target path falls outside the instance context. ### why does Atlas prompt for external_directory on Windows On Windows, Atlas normalizes the path with FSUtil.normalizePath before the containment check, so slash style is not the cause. A prompt means the normalized path really did resolve outside the instance context, so check the root the path was built from. ### is the external_directory prompt a bug in Atlas No. The external_directory prompt is the workspace boundary working as designed. An unexpected prompt usually means a stray absolute path, so inspect the path in the prompt before approving anything. ### does approving with always in Atlas grant access to one file or the whole directory Approving with `always` persists the directory glob that Atlas shows in the prompt, not the single file. Read that glob before accepting, because the approval covers everything under the parent directory. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/external-directory-permission-prompt Source of truth: aeo_pages row `/resources/troubleshooting/external-directory-permission-prompt` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.