Automate Your NAS File Organization with Claude Code, SSH, and Docker

A developer's guide to remote AI-powered file management using Claude Code, SSH tunneling, and containerized workflows

---

If you've ever stared at a chaotic NAS full of unorganized photos, videos, and documents, you know the pain. Manually sorting thousands of files is tedious, error-prone, and — frankly — a waste of your time. What if you could delegate that entire job to an AI agent running autonomously on your own infrastructure?

That's exactly what developer @LotusDecoder did, and the setup is elegant: use Claude Code on a remote server to SSH into a NAS, spin up a Docker container with elevated permissions, mount the NAS file system, and let Claude Code intelligently organize everything — photos, albums, videos, and more.

In this post, we'll break down how this architecture works, why it's powerful, and how you can replicate it yourself.

---

The Architecture: Claude Code → SSH → NAS → Docker → Claude Code (Again)

At first glance, the setup sounds like an Inception-style chain of tools. But each layer serves a clear purpose. Here's the full flow:

1. Claude Code on your remote server receives the task and the NAS's SSH credentials.
2. It SSHes into the NAS using those credentials.
3. Once inside, it launches a Docker container with the --dangerously-skip-permissions flag enabled, running Claude with the Opus model.
4. The NAS file directories are volume-mounted into the container.
5. The containerized Claude Code then autonomously organizes your files — sorting photos, labeling videos, restructuring folders, etc.

This layered design is intentional. Your primary Claude Code agent acts as the orchestrator, while a second sandboxed instance handles the actual file operations. The Docker container isolates the dangerous (but necessary) permission bypass from your host system, keeping things relatively safe while still enabling full file system access.

[Your Machine / CI Server]
        |
   Claude Code (Orchestrator)
        |
      SSH Connection
        |
   [NAS / Remote Server]
        |
   docker run --rm \
     -v /nas/files:/data \
     claude --dangerously-skip-permissions \
            --model opus
        |
   [Mounted NAS File System]
   /photos, /videos, /albums, ...

---

Setting It Up: Step-by-Step

Step 1: Configure SSH Access to Your NAS

Make sure your NAS supports SSH access (most Synology, QNAP, or TrueNAS devices do). Store the credentials securely — ideally using environment variables or a secrets manager rather than hardcoding them.

# Test your SSH connection manually first
ssh [email protected] -i ~/.ssh/nas_key

# Or using password auth (less recommended)
ssh [email protected]

In your Claude Code session on the server, you can provide the SSH connection details as part of the task context:

Task: Connect to the NAS at 192.168.1.100 using the provided SSH key.
Once connected, organize all files under /volume1/media into subfolders
by year, type (photos/videos), and event name where possible.

Step 2: Launch the Docker Container on the NAS

Once Claude Code is connected via SSH, instruct it to run a Docker container with the NAS directories mounted. The key flags here are:

• --dangerously-skip-permissions — bypasses Claude Code's built-in safety prompts, enabling fully autonomous operation
• --model opus — uses Claude's most capable model for nuanced file understanding
• -v — volume mounts your NAS storage into the container

docker run --rm -it \
  -v /volume1/photos:/data/photos \
  -v /volume1/videos:/data/videos \
  -v /volume1/albums:/data/albums \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/anthropics/claude-code:latest \
  claude --dangerously-skip-permissions --model opus

⚠️ Security Note: The --dangerously-skip-permissions flag removes interactive safety guards. Only use this in controlled environments — ideally within a Docker container with scoped volume mounts — so the AI cannot access anything outside the mounted directories.

Step 3: Define the File Organization Task

With the container running and the file system mounted, you can now prompt Claude Code to perform intelligent organization. Because Claude understands context, it can go far beyond simple renaming — it can infer event names from photo metadata, group videos by content type, and even flag duplicates.

Example task prompt:

You have access to the following directories:
- /data/photos — Contains thousands of unsorted JPEG/PNG files
- /data/videos — Contains MP4 and MOV files from various devices
- /data/albums — Target directory for organized output

Please:
1. Sort photos by year and month based on EXIF metadata
2. Group videos by approximate duration and resolution into subfolders
3. Create named albums for recurring events (birthdays, holidays, trips)
4. Generate a summary report of what was moved and why

Claude Code will execute shell commands, read file metadata, create directories, and move files — all autonomously.

---

Why This Approach Is Powerful

Full Autonomy Without Babysitting

Traditional file organization scripts are brittle. They rely on rigid naming conventions or folder structures. Claude Code understands intent. It can read filenames, parse EXIF data, examine video properties with ffprobe, and make intelligent decisions — just like a human assistant would, but faster and without breaks.

Isolated and Reproducible

Running Claude Code inside Docker means:

• Reproducibility — the same container image can be used every time
• Isolation — mistakes are contained to the mounted volumes
• Portability — the setup works on any NAS or server that runs Docker

Scalable to Complex Workflows

This pattern isn't limited to file organization. The same SSH + Docker + Claude Code architecture can be applied to:

• Media transcoding pipelines — detect and convert incompatible video formats
• Document indexing — extract text from PDFs and build searchable catalogs
• Backup auditing — verify backup integrity and flag missing files
• Duplicate detection — identify and quarantine redundant files before storage cleanup

---

Practical Considerations and Gotchas

Before you deploy this in production, here are a few things to keep in mind:

• API costs: Running Claude Opus on large directories (thousands of files) can consume significant tokens. Consider batching tasks or using Haiku for initial passes and Opus only for complex decisions.
• SSH key management: Store your NAS SSH key securely. Use ssh-agent or a vault solution — never expose it in plain text within a prompt or config file.
• Docker availability on NAS: Not all NAS firmware supports Docker natively. Synology DSM and QNAP QTS both have Docker support; TrueNAS Scale supports containers via Kubernetes.
• Rate limits: Anthropic's API has rate limits. For large operations, build in retry logic or introduce delays between file batches.
• Dry-run first: Always test with a --dry-run mode or a small subset of files before unleashing Claude on your entire library.

---

Conclusion

What @LotusDecoder demonstrated is more than a clever hack — it's a glimpse into how AI agents will increasingly manage our personal and professional infrastructure. The combination of Claude Code + SSH + Docker creates a surprisingly robust, autonomous, and flexible system for delegating complex file management tasks to an AI.

The beauty of this architecture is its composability. Claude Code acts as the intelligent brain, SSH is the secure transport layer, and Docker provides the safe sandbox for autonomous execution. Together, they turn a tedious weekend project into a set-and-forget workflow.

If you're managing a media server, running a homelab, or just drowning in disorganized files, this is absolutely worth experimenting with. Start small, define clear tasks, and watch Claude do the heavy lifting.

---

Have you tried using Claude Code for infrastructure automation? Share your setup in the comments or tag us on X. For more AI automation tutorials, explore the OpenClaw Skills library on ClawList.io.

Tags: claude-code docker ssh nas file-automation ai-devops homelab anthropic