> For the complete documentation index, see [llms.txt](https://handbook.harmonic.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.harmonic.security/handbook/3.-runtime-sandbox-and-autonomy/3.8-file-and-filesystem-access-controls.md). # 3.8 File and filesystem access controls How to scope which folders an agent can read and write, and how to keep home directories, secrets, and cloud-synced roots out of default access. *Last reviewed: August 18, 2026* {% hint style="info" %} File access should be scoped to the work. Keep home folders, cloud drives, and secret stores out of the agent's normal reach. {% endhint %} ## File and filesystem access controls: what security teams need to know Agents are often useful because they can read and edit files. That access should be intentional. A broad folder grant can expose unrelated projects, personal files, credentials, and synced documents. Good filesystem control starts before the session. Choose the workspace, exclude sensitive paths, decide what can be written, and make destructive actions hard to approve by accident. ## Common file and filesystem access controls security failures * The agent starts in the user's home directory. * Cloud-synced folders expose files from unrelated teams. * Secrets live in the same project root as the work. * Generated files overwrite source or evidence without review. * The agent can delete or rename broad directory trees. ## File and filesystem access controls security controls checklist * Start agents in a narrow project directory. * Keep home, Desktop, Downloads, cloud drives, password stores, and secret stores outside normal scope. * Use deny rules for `.env`, key files, tokens, and credential directories. * Require approval for deletes, moves, broad rewrites, and generated code touching sensitive paths. * Log denied reads and writes to sensitive locations. ## Anthropic ### Overview Claude Code is where filesystem policy is enforceable. It starts from read-only permissions and prompts before edits, and permission rules can deny reads and edits of specific paths such as .env files, key material, and credential directories. Deny rules take precedence over ask and allow, so a sensitive-path deny list holds even against a broad allow rule, and managed settings push those rules organization-wide, which is how a file-access standard becomes more than a team convention. Two adjacent surfaces widen local file reach: desktop extensions and local MCP servers run with local access on Claude Desktop and Claude Code, while Cowork remote sessions can reach folders connected through Claude Desktop only while that app is online. Those files are processed in the remote session on Anthropic's servers, and each local call is checked against the member's folder permissions. Managed Agents cloud sandboxes contain file work inside an isolated Linux container instead. Claude Tag channel sessions can read and write files inside their per-thread hosted sandbox, but files that exist only there disappear when the sandbox is released. Persisted outputs must be posted to Slack or pushed to a connected repository or service, which creates a separate sharing and authorization event. Do not confuse ephemeral sandbox storage with a guarantee that the thread, memory, transcript, or exported result is ephemeral. ### Anthropic documentation * [Configure permissions](https://code.claude.com/docs/en/permissions) * [Claude Code settings](https://code.claude.com/docs/en/settings) * [Claude Code security](https://code.claude.com/docs/en/security) * [Getting Started with Local MCP Servers on Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) * [Cloud sandbox reference](https://platform.claude.com/docs/en/managed-agents/cloud-sandboxes-reference) * [Claude Cowork architecture overview](https://support.claude.com/en/articles/14479288-claude-cowork-architecture-overview) * [Use Claude Cowork on web, desktop, and mobile](https://support.claude.com/en/articles/15520349-use-claude-cowork-on-web-desktop-and-mobile) * [Claude Tag security and data handling](https://claude.com/docs/claude-tag/concepts/security-and-data) ### Applicable Harmonic guides for Anthropic * [Securing Claude Cowork: A Security Practitioner's Guide](https://www.harmonic.security/resources/securing-claude-cowork-a-security-practitioners-guide) ## OpenAI ### Overview For Codex, sandbox mode is the filesystem policy. Read-only mode lets the agent inspect but not change files; workspace-write limits writes to the workspace, with command network access off by default; danger-full-access removes the boundary and belongs only in disposable environments. The mode names are the review vocabulary: "which mode, over which directory" answers most file-access questions, and approval policy governs when the agent can escalate past the mode's limits. Managed configuration can pin which sandbox modes and approval policies are available, so organizations can keep full access out of reach for standard users rather than relying on prompts. Desktop Work uses the same local permission plane as Codex and can open local folders or projects. Work on web and mobile cannot directly access computer files; it uses uploaded files, workspace resources, and connected systems instead. Treat those as data flows rather than filesystem grants. ### OpenAI documentation * [Codex sandboxing](https://developers.openai.com/codex/concepts/sandboxing) * [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security) * [Codex managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) * [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275) * [ChatGPT Work Admin FAQ](https://learn.chatgpt.com/docs/enterprise/work-admin-faq) ### Applicable Harmonic guides for OpenAI * [Securing Codex Best Practice](https://www.harmonic.security/resources/securing-codex-best-practice) ## Frequently asked questions about file and filesystem access controls ### What folders should AI agents access? Only the project directory the task needs, added explicitly and removed when the work ends. Broad grants such as home directories, Documents, or whole-drive access expose unrelated projects, personal files, and synced content the user forgot was there. The folder choice is the single highest-leverage filesystem control because everything else operates inside it. ### Should agents read `.env` files? Block them by default with deny rules, along with key files, token caches, and credential directories. If a task genuinely needs configuration, provide sanitized examples or inject secrets through an approved mechanism at runtime rather than letting the agent read live values. A leaked .env in a prompt or log is a credential incident, not a hygiene issue. ### Are cloud-synced folders safe? They are risky as agent workspaces on two counts: they often contain files from unrelated teams and projects, and agent writes propagate through sync, so an unwanted mass edit or delete replicates to every device and collaborator before anyone reviews it. Prefer a local, narrowly scoped project directory and copy results into synced locations deliberately. ### How should deletes be handled? Require explicit approval for deletes, renames, moves, and any operation touching many files, and make the approval show the full scope before it executes. Version control is the safety net for repositories; for everything else, prefer soft-delete or staging patterns so a wrong approval is recoverable. ### What file activity should be logged? For the filesystem specifically: denied reads and writes on sensitive paths, which are the high-signal events, plus successful writes and deletes with paths, the workspace root for the session, and any change to file-access policy itself. Pair this with the session-level sandbox-mode logging from 3.1 so an investigator can tie a file event to the boundary that allowed it. ## Applicable regulations and frameworks | Governance page | Relationship to this article | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | G.1 Map your controls to NIST AI RMF and CSF 2.0 | This article supplies implementation evidence for the NIST AI RMF and matching NIST CSF 2.0 outcomes. | | G.3 DORA and AI resilience in financial services | Conditional: for a DORA-regulated workflow, this supports ICT containment, resilience, continuity, and recovery. | | G.5 SANS Critical AI Security Guidelines mapping | This article implements relevant SANS Deployment Strategies and Inference Security guidance. | | G.6 Write an AI Acceptable Use Policy that holds up | This article supplies a technical or process control used to enforce the acceptable-use policy. | | G.7 Ownership and RACI for AI security | This control depends on the ownership and evidence responsibilities defined in the RACI. | | G.9 HIPAA controls for AI systems handling PHI | Conditional: for a workflow handling ePHI, this supports HIPAA technical access, integrity, transmission, availability, and audit safeguards. | *G.2, G.3, G.4, and G.9 are conditional mappings. They apply only when the deployment is within the legal or regulatory scope described on the linked governance page.* ## Related handbook guidance * [3. Runtime, Sandbox & Autonomy](/handbook/3.-runtime-sandbox-and-autonomy.md) * [3.1 What Even is an AI Sandbox?](/handbook/3.-runtime-sandbox-and-autonomy/3.1-what-even-is-an-ai-sandbox.md) * [4.7 Secrets and credential hygiene in prompts and tools](/handbook/4.-data-protection-and-residency/4.7-secrets-and-credential-hygiene-in-prompts-and-tools.md) * [5.2 Data exfiltration via tools and connectors](/handbook/5.-threats-and-adversarial/5.2-data-exfiltration-via-tools-and-connectors.md) * [6.2 OpenTelemetry for AI runtime visibility](/handbook/6.-observability-audit-and-evidence/6.2-opentelemetry-for-ai-runtime-visibility.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://handbook.harmonic.security/handbook/3.-runtime-sandbox-and-autonomy/3.8-file-and-filesystem-access-controls.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.