18 KiB
| slug | title | author | status | created | updated | content_type | primary_keyword | secondary_keywords | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| claude-virtual-filesystem-guide | Inside Claude's Sandbox: What Happens When Claude Creates a File | henry | outline | 2024-12-25 | 2024-12-25 | debugging-story | claude file creation |
|
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 (120-150 words)
Purpose: Hook reader with professional curiosity, promise deep understanding
Approach: First-person exploration angle. Henry digs deeper because he wants to understand the system, not because he's lost.
Must include:
- Moment of curiosity (found file easily, but wanted to understand the system)
- Professional interest signal — "how does this actually work?"
- Promise: "Here's what I discovered when I mapped the whole thing."
Hook angle (Option A — curiosity):
"Claude created the file. I found it in the sidebar in 5 seconds. But then I wondered — where is it physically? What's the filesystem structure inside? I went exploring."
Hook angle (Option B — scaling up):
"When you start working with Claude on real projects, you eventually hit the question: how exactly is its filesystem organized? I decided to figure it out."
Transition: "Let me show you what's actually happening under the hood."
H2: The Quick Answer (80-100 words)
Purpose: Give impatient readers the core answer immediately
Must cover:
- Claude runs in Ubuntu sandbox container
- Key path:
/mnt/user-data/outputs/= sidebar downloads /home/claude/= temp workspace (disappears)
Structure:
- One-liner: where files actually go
- Why some files "disappear"
- Tease: "But there's more to it. Let me show you the full map."
Note: This follows Henry's "don't bury the lede" principle.
H2: The Filesystem Map (200-250 words)
Purpose: Complete reference of sandbox structure
Must cover:
/mnt/user-data/uploads/— your uploaded files/mnt/user-data/outputs/— files that appear in sidebar/home/claude/— temp working directory/mnt/skills/— Claude's built-in capabilities- Note:
/mnt/project/for Projects feature
Structure:
- Brief intro: "Here's the full structure I mapped out."
- Table with 4-5 key directories
- Key insight: only
/mnt/user-data/outputs/= downloadable
Table format:
| Path | What's there | Persists? |
|------|--------------|-----------||
| /mnt/user-data/uploads/ | Your uploaded files | Session |
| /mnt/user-data/outputs/ | Files for download | Session |
| /home/claude/ | Claude's workspace | ❌ No |
| /mnt/skills/ | Built-in capabilities | Read-only |
Code example:
view /mnt/user-data/
Shows: uploads/, outputs/ structure
Transition: "So why do files sometimes not appear in your sidebar?"
H2: The Problem: Where Did My File Go? (150-180 words)
Purpose: Explain the common frustration point
Must cover:
- Claude sometimes creates in
/home/claude/(temp, not visible) - Files there won't appear in sidebar
- Claude "forgets" to move to outputs
- Second issue: Filesystem MCP confusion (Claude Desktop)
Structure:
- The problem: Claude creates file in wrong place
- Why it happens:
/home/claude/is default working dir - Extra confusion: MCP vs sandbox (brief mention)
Key insight:
"Claude's sandbox resets between conversations. If a file is in
/home/claude/and you close the chat — it's gone."
⚠️ TODO: Verify this claim with testing. Need to confirm sandbox reset behavior.
Transition: "Here's how to make sure your files end up where you can actually get them."
H2: The Fix: How to Direct Claude (150-200 words)
Purpose: Give actionable solution
Must cover:
- Explicit instruction: "save to /mnt/user-data/outputs/"
- Example prompts that work
- For MCP users: specify "use filesystem MCP" vs sandbox
Structure:
- What to say to Claude (prompt examples)
- For MCP users: disambiguation
Prompts that work:
"Create the file and save it to /mnt/user-data/outputs/"
"Copy this file to /mnt/user-data/outputs/"
"Use filesystem MCP to save to ~/Projects/myapp/image.png"
Transition: "Now, which approach should you actually use?"
H2: Two Strategies for File Workflows (200-250 words)
Purpose: Help reader choose their approach based on workflow type
Must cover:
- Strategy 1: Sandbox for iterative work
- Strategy 2: MCP for automation
- When to use each (clear criteria)
Structure:
Strategy 1: Sandbox-first (iterative editing)
- Work in
/home/claude/during conversation - Use
str_replacetool for line-by-line edits - Copy to outputs when done
- Pros: faster iteration, built-in editing tools, no filesystem noise
- Cons: files not visible in sidebar until you copy them out
- Best for: iterative work on a single file, multiple rounds of edits, refactoring
Strategy 2: MCP-first (automation)
- Claude saves directly to local filesystem via MCP
- Pros: files persist immediately in your project, no extra step
- Cons: no
str_replacetool, requires MCP setup, Claude Desktop only - Best for: generating multiple files at once, scaffolding, automated workflows
Key difference to highlight:
Sandbox has
str_replacefor precise line-by-line editing. MCP doesn't. Choose based on whether you need iteration or automation.
One-liner summary:
"Sandbox for iteration. MCP for automation."
H2: Try It Yourself (100-130 words)
Purpose: Reader engagement, verification
Must cover:
- 3 quick commands to explore their own sandbox
- What to look for
Exercises:
"Show me view /mnt/user-data/"— see your structure"Create test.txt with 'hello' and show me where it went"— test file creation"List contents of /home/claude/"— see temp workspace
Note: Remind that this requires Pro+ plan.
H2: Project Instructions for File Handling (150-180 words)
Purpose: Give readers ready-to-use instructions they can add to Claude Projects
Must cover:
- Example instruction for sandbox-first workflow
- Example instruction for MCP-first workflow
- How to specify which tool to use
Example 1 — Sandbox-first (for iterative work):
File handling:
- Work with files in /home/claude/ during conversation
- Use str_replace for edits
- Copy final versions to /mnt/user-data/outputs/ before finishing
Example 2 — MCP-first (for automation):
File handling:
- Use filesystem MCP to save files directly to project directory
- Do not use sandbox for file operations
- Save to: ~/Projects/[project-name]/
Example 3 — Hybrid (explicit routing):
File handling:
- For iterative editing: use sandbox + str_replace, copy to outputs when done
- For generating new files: use filesystem MCP to save directly to ~/Projects/
- Always confirm which method before creating files
Note: These go in Project Instructions or system prompt.
Callout Box: Artifacts ≠ Files (60-80 words)
Purpose: Address common terminology confusion
Placement: As sidebar/callout, possibly after "The Fix" or near end
Must clarify:
- Artifacts: interactive previews (HTML, React, SVG) — render in sidebar
- Files: actual downloadable documents (.docx, .xlsx, .pdf)
- Different features, different behavior
Closing (80-100 words)
Purpose: Wrap up with practical takeaway
Approach: Henry-style direct ending. No fluff.
Must include:
- One-sentence summary of key insight
- Clear CTA (explore your sandbox)
- Sign-off phrase
Draft closing:
"That's it. Claude's sandbox isn't magic — it's just Ubuntu with a specific folder structure. Know the paths, and you'll never lose a file again."
"Now go explore your own sandbox. And maybe save that important file before you close the chat."
Word Count Breakdown
| Section | Words |
|---|---|
| Opening | 130 |
| The Quick Answer | 90 |
| The Filesystem Map | 220 |
| The Problem | 160 |
| The Fix | 180 |
| Two Strategies | 230 |
| Try It Yourself | 110 |
| Project Instructions | 160 |
| Callout: Artifacts ≠ Files | 70 |
| Closing | 90 |
| Total | ~1440 |
Target: 1200-1500 (debugging story range) ✓
Code Examples Plan
| Section | Type | Purpose | Lines |
|---|---|---|---|
| Filesystem Map | Command | Show structure | 1 |
| Filesystem Map | Output | Example result | 4-5 |
| The Fix | Prompt | Working instruction | 1 |
| The Fix | Prompt | MCP instruction | 1 |
| Try It Yourself | Commands | Reader exercises | 3 |
Code ratio: ~15-20% (appropriate for debugging story)
Visual Elements Plan
| Element | Section | Description |
|---|---|---|
| Screenshot 1 | Filesystem Map | Output of view /mnt/user-data/ |
| Screenshot 2 | The Problem | File in sidebar (successful) |
| Screenshot 3 | Try It Yourself | Optional: annotated sandbox structure |
| Table | Filesystem Map | Directory reference |
| Callout box | After The Fix | Artifacts vs Files clarification |
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 Filesystem Map section present
- Code examples complete and accurate
- Project Instructions section has 3 ready-to-use examples
- Callout box for Artifacts/Files distinction included
- Closing has practical CTA, no fluff
- First-person voice throughout
- No forbidden phrases (see Henry guide)
- ⚠️ Sandbox reset claim verified before publishing
Outline created: 2024-12-25 Ready for: @writer