24 KiB
| slug | title | author | status | created | updated | content_type | primary_keyword | secondary_keywords | assets_folder | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| claude-virtual-filesystem-guide | Inside Claude's Sandbox: What Happens When Claude Creates a File | henry | outline | 2024-12-25 | 2026-01-06 | debugging-story | claude file creation |
|
assets/claude-virtual-filesystem-guide/ |
Brief
Strategic Context
Why This Article?
No one has documented Claude's internal sandbox filesystem structure in claude.ai. Users encounter frustration when files "disappear" or Claude creates files in the wrong location. This is Henry's first article — establishes technical credibility with an original investigation that provides real value.
Availability: Code execution and file creation requires paid plans (Pro, Max, Team, Enterprise). Free plan only has Artifacts.
Target Reader
- Role: AI-first developer using Claude Pro/Max with "Code execution and file creation" enabled
- Situation: Using Claude for code generation, file creation, possibly with Filesystem MCP in Claude Desktop
- Pain: Files created by Claude don't appear where expected; confusion between internal sandbox and Filesystem MCP
- Search query: "claude file creation not working", "where does claude save files", "claude mcp vs sandbox"
Terminology Clarification (for article)
| Term | What it means |
|---|---|
| "Code execution and file creation" | Official Anthropic name for sandbox feature in claude.ai |
| Sandbox / Sandboxed environment | Ubuntu container where Claude runs code |
| Artifacts | Interactive previews (HTML, React, SVG) — separate feature from file creation |
| Filesystem MCP | External MCP server for local file access (Claude Desktop only) |
| "Virtual filesystem" | NOT official term, but Claude understands it in conversation — tested in practice |
Success Metrics
- Primary: Organic traffic from developers searching for Claude file issues
- Secondary: Social shares from AI dev communities (Reddit, Twitter, Dev.to)
SEO Strategy
Keywords
| Type | Keyword | Notes |
|---|---|---|
| Primary | claude file creation | High intent, problem-focused |
| Secondary | claude sandbox environment | Technical term users encounter |
| Secondary | claude mcp filesystem | Confusion point we address |
| Secondary | claude virtual filesystem | Descriptive, long-tail |
Search Intent
User expects: practical explanation of where Claude stores files, how to find them, how to control file location.
Competition
- Anthropic docs exist but are high-level, don't show internal paths
- No articles specifically about
/mnt/user-data/structure - Our angle: hands-on investigation with screenshots and "try it yourself" exercises
Unique Angle
First-hand debugging story with reproducible experiments. Reader can follow along and discover the filesystem themselves.
Content Requirements
Core Question
Where do files go when Claude creates them, and how do I make Claude save files where I actually want them?
Must Cover
- Sandbox filesystem structure overview (key folders and their purposes)
- What happens when Claude creates a file (step by step)
- The
/mnt/user-data/outputs/→ sidebar connection - Problem: Claude confusing internal sandbox vs Filesystem MCP (in Claude Desktop)
- Solution: how to direct Claude to the right tool
- Two strategies for file workflows (see below)
- "Try it yourself" experiments for readers
- Quick note: this requires paid plan (Pro+)
Two File Workflow Strategies (new section)
Strategy 1: Work in sandbox, save at end
- Work with files inside
/home/claude/during conversation - Only move to
/mnt/user-data/outputs/when done - Pros: Faster iteration, no filesystem noise, sandbox is temp anyway
- Cons: Lose work if you forget to save, files not visible until end
Strategy 2: Save to local disk immediately (via Filesystem MCP)
- Claude saves directly to local filesystem via MCP
- Pros: Files persist immediately, work directly with your project files
- Cons: Requires MCP setup in Claude Desktop, can't use in claude.ai web
Must NOT Cover
- MCP server installation guide (separate topic, just mention it exists)
- API code execution tool (different product)
- Artifacts deep dive (mention briefly for context on naming confusion)
Note on Artifacts vs Files (sidebar box)
Users often confuse "artifacts" and "files":
- Artifacts (June 2024): Interactive previews that render in sidebar — HTML, React, SVG, code snippets
- Files (September 2025): Actual downloadable documents — .docx, .xlsx, .pdf, created via sandbox
Artifacts had a highlight+edit feature (September 2024) where you could select code and click "Improve" or "Explain". This may have changed after the October 2025 UI update when Code Execution became default. The current interface separates Artifacts from file creation more clearly.
Unique Angle
Personal debugging story: "I spent hours confused about where my files went. Here's what I discovered."
Banatie Integration
- Type: none
- Rationale: First Henry article, establish credibility first. No forced mentions.
Structure Guidance
Suggested Flow
- Opening hook: The frustration — "Claude said it created the file. But where is it?"
- The investigation: How I started exploring with
view /commands - The map: Key folders explained with table
- The gotcha: Sandbox vs Filesystem MCP confusion
- The fix: Specific prompts that work
- Two strategies: Sandbox-first vs Local-first workflows
- Try it yourself: Commands readers can run
- Quick reference: Cheat sheet
Opening Hook
Start with the specific frustration moment. First-person, relatable. No definitions.
Closing CTA
"Now you know where Claude keeps its files. Go explore your own sandbox — and stop losing your work."
Visual & Interactive Elements
Screenshots Needed
- Sidebar showing files in outputs folder
- Result of
view /mnt/user-data/showing structure - Example of Claude creating file "not in outputs" (the problem)
Code Snippets for Article
view /
view /mnt/user-data/
view /home/claude/
"Try It Yourself" Exercises
- "Ask Claude:
view /mnt/user-data/— what do you see?" - "Ask Claude to create a test file. Check: did it appear in sidebar?"
- "If you have MCP configured, ask Claude to save via filesystem MCP specifically"
Screenshot Flow (for Oleg to capture)
Create a fresh chat with Code Execution enabled. Run these in sequence:
Step 1: "Show me the root filesystem structure with view /"
Screenshot: The output showing available directories
Step 2: "Show me what's in /mnt/user-data/"
Screenshot: uploads/, outputs/ structure
Step 3: "Create a simple test.txt file with 'hello world' content"
Screenshot: Where Claude creates it (likely /home/claude/ or outputs/)
Step 4: "Show me /mnt/user-data/outputs/"
Screenshot: Verify file appears (or doesn't)
Step 5: Check sidebar
Screenshot: File appearing in download area
Step 6 (if MCP configured in Claude Desktop):
"Use filesystem MCP to save a file to ~/Desktop/test-mcp.txt"
Screenshot: Compare behavior — file goes to actual local disk
References
Official Documentation
- https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude (main reference)
- https://docs.claude.com/en/release-notes/claude-apps (timeline of features)
Research Sources
- Personal investigation by author
- Simon Willison's analysis: https://simonwillison.net/2025/Sep/9/claude-code-interpreter/
Background Context (for author reference, not for article)
- Artifacts launched June 2024, got highlight+edit September 2024
- "Analysis tool" (JS-based) launched October 2024
- Code Execution (Python/Node sandbox) replaced Analysis tool September 2025
- October 2025: Code Execution became default for paid plans, UI changed
- Users report highlight+edit feature may work differently now
Competitor Articles
- None directly covering this topic (unique content opportunity)
Brief created: 2024-12-25 Ready for: @architect
Outline
Pre-Writing Notes
Author: henry Voice reference: style-guides/henry-technical.md Word target: 1200 words (range: 800-1500) Content type: debugging-story
Key style points from Henry's guide:
- Opening: Start with problem/frustration, not definitions (Section 2)
- Sections: 150-300 words, paragraphs max 4 sentences (Section 2)
- Code ratio: 20-30% for debugging stories (Section 4)
- Closing: Practical next step, "Go build something." (Section 2)
- Voice: Direct, confident, first-person, "Here's the thing about..." (Section 1)
Article Structure
H1: Inside Claude's Sandbox: What Happens When Claude Creates a File
Contains primary keyword: "claude file creation"
Opening
Hook:
Did you know that every Claude conversation has its own sandbox container with a filesystem and persistent volumes? Understanding how they work and how Claude uses them gives you a significant advantage when working with this AI. While this is an internal part hidden under the hood, knowing how to work with it makes you more effective — and in some cases saves your time and work results.
Transition: "Let me show you what's actually happening under the hood."
H2: The Filesystem Structure
Purpose: Show key directories and their purposes immediately
Table:
| Path | Contents | Persistence |
|---|---|---|
/mnt/user-data/uploads/ |
Files uploaded by user | Persistent |
/mnt/user-data/outputs/ |
Downloadable files visible in sidebar | Persistent |
/home/claude/ |
Claude's workspace | ⚠️ No guarantee of long-term persistence |
/mnt/skills/ |
Built-in capabilities | Read-only |
Pro Tip (callout box):
Files in
/home/claude/can also be opened in the sidebar — just click on the file in the chat where tool output is displayed (file creation or editing).
H2: What Happens When Claude Creates a File
Purpose: Explain the two-step process
Steps:
- Claude creates the file in
/home/claude/ - Claude copies it to
/mnt/user-data/outputs/
Key insight: There are actually TWO copies of the file.
H2: Common Problems and How to Solve Them
Disclaimer: In simple scenarios Claude works well, but in more complex cases things may not go as planned. Don't panic about "where's my file?"
Problems covered:
- Claude created a file but didn't copy it to outputs
- Claude edited the version in
/home/claude/instead of/mnt/user-data/outputs/ - How to see files you shared with Claude during the conversation
- ⚠️ Warning: Files in
/mnt/user-data/are persistent, but be careful with/home/claude/— files there may disappear after some time
H2: Walkthrough — The File Lifecycle in Action
@writer NOTE: This section is a detailed walkthrough provided by Oleg. Transform into flowing narrative text while preserving ALL steps, observations, and warnings. The sequence and insights are essential — do not remove or reorder without approval. Screenshots are ready in assets folder.
Purpose: Demonstrate the full file lifecycle through a practical example — building a news compilation document.
Step 1: Creating an Internal File
User prompt:
Your task is to find and compile AI news into a single markdown document. Here's how we'll work:
**Workflow:**
1. I give you a topic or search query
2. You search the web, find relevant news, select the single best match, and append it to the document
3. We repeat steps 1-2 until I say "done"
4. You show me the complete document for final review
**Rules:**
- Only one news item per search — pick the most relevant result
- All items go into the same file (append, don't overwrite)
- For each item include: headline, source, date, and a 2-3 sentence summary
Let's start.
Search for: the funniest AI news from the last two months
Screenshot: screenshots/s1.png
Key observation: We deliberately did NOT specify where to create the file. We hinted that we plan to continue working with it and don't need it immediately. This simulates the scenario where Claude creates an internal working file without showing it to the user right away.
Result: Claude creates ai-news-compilation.md in /home/claude/. The file is NOT visible in the sidebar.
Step 2: Appending More Content
User prompt:
Now find the most important news about AI image generation for the last two months
Screenshot: screenshots/s2.png
Key observation: The file is still not visible in sidebar, but we can see Claude continues working with it using the str_replace tool (for editing/appending content).
Step 3: Viewing the Internal File (Option 1 — Click in Tool Output)
Question: What if we want to see the file contents at this point?
Option 1: Click on the filename in the tool output within the chat.
Screenshot: screenshots/s3.png — Arrow pointing to clickable filename in tool output
Result: The file opens in the sidebar preview panel.
Screenshot: screenshots/s4.png — File content visible, but NOT in sidebar file list
Key observation: The file opens and we can read its contents. However, it does NOT appear in the sidebar's file list — it's just a preview.
⚠️ Warning: Files in the internal sandbox (/home/claude/) are NOT persistent. They may be deleted when the container times out or the session ends. Be careful!
Step 4: Moving File to Outputs (Option 2 — Make Persistent)
User prompt:
move this file to /mnt/user-data/outputs/
Screenshot: screenshots/s5.png
Result: Claude uses bash tool with mv /home/claude/ai-news-compilation.md /mnt/user-data/outputs/. The file now appears in the sidebar's Artifacts list and is available for download.
Key observation: Since we MOVED (not copied) the file, Claude now has only ONE file to work with — in the outputs directory. We can continue adding news and see changes immediately in the sidebar.
Step 5: Continue Working (Happy Path)
User prompt:
Find the biggest Open Source AI related release for the last two months
Result: Claude appends to the same file. Since the file is now in /mnt/user-data/outputs/, changes are visible immediately in the sidebar.
Interlude: Understanding present_files Tool
Important concept: Claude has a present_files tool for finalizing work on a file. This is what Claude uses by default when completing work. It does the following:
- Copies the file to
/mnt/user-data/outputs/ - Opens it immediately in the sidebar preview
- Signals to Claude that work on this file is "complete" (though further modifications are still possible)
The catch: After present_files, there are now TWO copies of the file — one in /home/claude/ and one in /mnt/user-data/outputs/.
Verify this yourself:
view /home/claude
and
view /mnt/user-data/outputs/
Step 6: The "Wrong File" Problem
User prompt:
The next task is to find the most performant AI coding agent released for the last two months
Screenshot: screenshots/s7-wrong-file-edited.png
What happens: Claude edits the file in /home/claude/ (the working copy), NOT the one in /mnt/user-data/outputs/.
Result: We see in the chat that Claude made changes, but the file in the sidebar remains unchanged. This is the moment for panic — but not for us. Now we understand what's happening.
Step 7: The Fix
User prompt:
please move this file from /home/claude to /mnt/user-data/outputs/ (override the existing file)
Screenshot: screenshots/s8.png
Result: Claude copies the updated file to outputs, overwriting the old version. The sidebar now shows all the news items including the latest addition.
Summary: What We Learned
- Claude creates working files in
/home/claude/by default - Files only appear in sidebar when in
/mnt/user-data/outputs/ - You can view internal files by clicking on them in tool output
present_filescreates a COPY — resulting in two files- Claude may edit the "wrong" file if duplicates exist
- Solution: explicitly move/copy to outputs when needed
H2: Quick Reference — Tools and Commands
Purpose: Hands-on reference for readers
Key tools Claude uses internally:
view— view files and directory contentsstr_replace— edit files by replacing textcreate_file— create new filesbash_tool— execute shell commands (ls, cp, mv, cat, etc.)present_files— make files available for download in sidebar
What readers should try (natural language prompts):
- "Show me what's in /mnt/user-data/" → triggers view
- "Create a file test.txt with 'hello world'" → triggers create_file
- "Run
ls -la /home/claude/" → triggers bash - "Copy test.txt to /mnt/user-data/outputs/" → triggers bash (cp)
- "Show me the file for download" → triggers present_files
Note: Tool names are internal implementation details. Users interact via natural language — Claude picks the right tool automatically.
Reminder: This requires Pro+ plan.
H2: Two Strategies for File Workflows
Purpose: Explain Filesystem MCP as an additional method for file storage on external disk
Strategy 1: Sandbox (built-in)
- Files stay in Claude's container
- Pros: works out of the box, no setup needed
- Cons: potential persistence issues in
/home/claude/
Strategy 2: Filesystem MCP (external storage)
- Files saved directly to your local disk
- Pros: true persistence, files in your project, version control
- Cons: requires MCP setup, Claude Desktop only
Summary: Sandbox for quick work, MCP for serious projects.
H2: Fun Part — Experimenting
The Two-Tab Experiment:
- Create a file with some text in Tab 1
- Open the same chat in Tab 2
- In Tab 2, ask to modify the file
- Return to Tab 1, ask to show file contents
- Contents match the changes from Tab 2
- Claude is surprised — he doesn't see the modification command in Tab 1's history
→ Demonstrates that the sandbox is shared across all sessions of the same chat
Closing
Purpose: Wrap up with practical takeaway
Approach: Henry-style direct ending. Short, no fluff.
Must include:
- One-sentence summary of key insight
- Clear CTA
Word Count Breakdown
| Section | Words |
|---|---|
| Opening | 100 |
| The Filesystem Structure | 150 |
| What Happens When Claude Creates a File | 100 |
| Common Problems and How to Solve Them | 150 |
| Walkthrough — The File Lifecycle in Action | 450 |
| Quick Reference — Tools and Commands | 100 |
| Two Strategies for File Workflows | 150 |
| Fun Part — Experimenting | 120 |
| Closing | 80 |
| Total | ~1400 |
Target: 1200-1500 (debugging story range) ✓
Note: Walkthrough section is longer due to code blocks and step-by-step format. Actual prose is ~300 words.
Code Examples Plan
| Section | Type | Purpose | Lines |
|---|---|---|---|
| The Filesystem Structure | Command | view /mnt/user-data/ |
1 |
| The Filesystem Structure | Output | Directory listing | 4-5 |
| What Happens When Claude Creates a File | Code | File creation flow | 2 |
| Walkthrough Step 1 | Prompt | News compilation task prompt | 15 |
| Walkthrough Step 2 | Prompt | Add more news | 1 |
| Walkthrough Step 4 | Prompt | Move to outputs | 1 |
| Walkthrough Interlude | Commands | view /home/claude, view outputs | 2 |
| Walkthrough Step 6 | Prompt | Find coding agent news | 1 |
| Walkthrough Step 7 | Prompt | Move with override | 1 |
| Quick Reference | Commands | view, create, bash examples | 5-6 |
| Fun Part — Experimenting | Prompt | Two-tab experiment steps | 3-4 |
Code ratio: ~25-30% (appropriate for debugging story with walkthrough)
Visual Elements Plan
| Element | Section | Description | File |
|---|---|---|---|
| Screenshot 1 | Walkthrough Step 1 | Claude creates internal file, not in sidebar | s1.png |
| Screenshot 2 | Walkthrough Step 2 | str_replace tool editing file | s2.png |
| Screenshot 3 | Walkthrough Step 3 | Clickable filename in tool output | s3.png |
| Screenshot 4 | Walkthrough Step 3 | File preview open, not in file list | s4.png |
| Screenshot 5 | Walkthrough Step 4 | File moved to outputs, visible in sidebar | s5.png |
| Screenshot 6 | Walkthrough Step 6 | Wrong file edited problem | s7-wrong-file-edited.png |
| Screenshot 7 | Walkthrough Step 7 | Fix — file moved/overwritten | s8.png |
| Table | The Filesystem Structure | Directory reference (paths, contents, persistence) | — |
Screenshots Status
All screenshots are ready in assets/claude-virtual-filesystem-guide/screenshots/:
s1.png— Initial file creations2.png— Appending with str_replaces3.png— Clickable filename (with arrow)s4.png— File preview vs file lists5.png— Move to outputs results6-present-files.png— (available, not used in walkthrough)s7-wrong-file-edited.png— Wrong file editeds8.png— Fix applied
@writer: Use relative paths like screenshots/s1.png when embedding images.
SEO Notes
- H1 contains: "Claude" + "File" (variant of primary keyword)
- H2s with keywords: "Filesystem", "File Workflows"
- First 100 words include: "Claude", "file", "created" (primary keyword area)
- Meta description: @writer to draft — focus on "where Claude saves files"
Quality Gates for @writer
Before submitting draft:
- Opening starts with curiosity/professional interest, not frustration or confusion
- "Here's the thing..." or similar Henry phrase used
- All "Must include" items covered
- Word counts within range per section
- Table in The Filesystem Structure section present
- Code examples complete and accurate
- Two-tab experiment clearly explained in Fun Part section
- Closing has practical CTA, no fluff
- First-person voice throughout
- No forbidden phrases (see Henry guide)
Outline created: 2024-12-25 Ready for: @writer
Validation Request
Status: Not required
This article is a technical tutorial/debugging-story based on personal investigation. All claims are verified through hands-on testing, not external sources.
Technical claims verified by user (2026-01-06):
- Filesystem structure (/mnt/user-data/, /home/claude/)
- File consistency across browser tabs
- Two-tab experiment behavior
No external fact-checking needed — proceed to @writer.
Verified Facts
✅ Проверено пользователем 2026-01-06:
-
Консистентность файлов между вкладками: Файлы в
/home/claude/доступны одновременно из любой вкладки браузера или Desktop версии с тем же чатом -
Структура /mnt/user-data/:
uploads/— файлы, загруженные пользователемoutputs/— файлы, отображаемые в sidebar
-
Доступ к файлам из /home/claude/: Файлы из
/home/claude/НЕ отображаются в списке sidebar, но доступны по клику на файл в выводе tool (создание, редактирование) прямо в чате -
Эксперимент с двумя вкладками:
- Создаём файл с текстом в Tab 1
- Открываем тот же чат в Tab 2
- В Tab 2 просим изменить файл
- Возвращаемся в Tab 1, просим вывести содержимое
- Содержимое соответствует изменению из Tab 2
- Claude удивлён — он не видит команду изменения в истории Tab 1
→ Демонстрирует, что sandbox — общий для всех сессий одного чата