# Mount Locally

**Page:** foundation/storage/mount-locally

[Download Raw Markdown](./foundation/storage/mount-locally.md)

---

# Mount Locally

**Access your container's filesystem from your local machine.** You mount the container's storage on YOUR computer (client-initiated), giving you drag-and-drop file access while keeping full control—your machine connects to the container, not the other way around.

**Why this is practical:**
- ✅ **Your data, your control** - You initiate the connection from your local machine
- ✅ **Bridge cloud and local** - Edit container files with local tools (VS Code, Photoshop, Excel)
- ✅ **No container changes needed** - SFTP via Hoody SSH Proxy, WebDAV via hoody-files
- ✅ **Familiar file managers** - Use Finder/Explorer like any network drive

---

## API Endpoints Summary

**File Access:**
- **[Hoody Files API](/api/files/)** - HTTP-based filesystem operations
- **[File Protocols](/api/files/mount/protocols/)** - SFTP/WebDAV backend mounting (as client)

**Related Access:**
- **[SSH Access](/foundation/networking/ssh/)** - Secure shell for command-line operations
- **[Hoody Terminal](/kit/terminals/)** - Web-based shell (no mounting needed)

---

## How It Works

**TWO protocols for local mounting:**



**Provided by: Hoody API (SSH Proxy)**

- Built on SSH protocol (port 22)
- Same infrastructure as SSH access
- Same authentication (SSH keys)
- Privacy-preserving routing
- Universal SFTP client support



**Provided by: hoody-kit (hoody-files service)**

- HTTP/HTTPS-based protocol
- Authentication via Proxy Permissions
- Native macOS/Windows support
- Mount directly in file managers
- Works through firewalls easily



**Both protocols access the SAME container filesystem.** SFTP via Hoody API, WebDAV via hoody-kit.

---

## SFTP Mounting

**SFTP provided by Hoody API's SSH Proxy—same infrastructure as SSH access.**


**SFTP vs SSH distinction**: SFTP is **NOT provided by hoody-files**. It's part of the **Hoody API's SSH Proxy** infrastructure. Only WebDAV is provided by hoody-files (hoody-kit).


### Requirements


**SSH key required:** SFTP uses SSH authentication. Your container must have an `ssh_public_key` configured. See [SSH Access](/foundation/networking/ssh/) for key generation.


### Connection Details

```bash
Protocol: SFTP (SSH File Transfer Protocol)
Host: ssh.{server-name}.containers.hoody.icu
Port: 22
Username: root
Authentication: SSH public key
```

**You mount FROM your local machine TO the container** - client-initiated connection for security and control.

**Example:** If your container is on server `us-west-1`, the SFTP host is:
```
ssh.us-west-1.containers.hoody.icu
```

**Privacy benefit:** Same endpoint for ALL containers on that server. SFTP routing happens by SSH public key during handshake—not visible in connection URL.

---

### Mount in macOS Finder


  
    1. **Open Finder** → **Go** menu → **Connect to Server** (⌘K)
    2. **Server Address:**
       ```
       sftp://ssh.us-west-1.containers.hoody.icu
       ```
    3. Click **Connect**
    4. **Authentication:**
       - Select your SSH private key from keychain
       - Or add new key: Keychain Access → add `~/.ssh/hoody-container-1`
    5. Container filesystem mounts as network drive
    
    **Mounted at:** `/Volumes/ssh.us-west-1.containers.hoody.icu/`
  
  
  
    ```bash
    # Mount via sshfs (requires osxfuse/macFUSE)
    brew install macfuse
    brew install gromgit/fuse/sshfs-mac
    
    # Create mount point
    mkdir -p ~/Hoody/container-1
    
    # Mount container
    sshfs root@ssh.us-west-1.containers.hoody.icu:/ \
      ~/Hoody/container-1 \
      -o IdentityFile=~/.ssh/hoody-container-1
    
    # Access files
    ls ~/Hoody/container-1/hoody/storage
    
    # Unmount when done
    umount ~/Hoody/container-1
    ```
  


---

### Mount in Windows Explorer


  
    **Download:** [WinSCP](https://winscp.net/)
    
    1. **New Site:**
       - File protocol: **SFTP**
       - Host name: `ssh.us-west-1.containers.hoody.icu`
       - Port: `22`
       - User name: `root`
    
    2. **Authentication:**
       - Advanced → SSH → Authentication
       - Private key file: Browse to `%USERPROFILE%\.ssh\hoody-container-1`
       - WinSCP converts to .ppk format automatically
    
    3. **Login** - Container filesystem appears in WinSCP's file manager
    
    4. **Optional:** Tools → Preferences → Integration → Explorer
       - Enable "Windows Explorer integration"
       - Access via right-click "WinSCP" in Explorer
  
  
  
    1. **Edit → Settings → Connection → SFTP**
       - Add key file: `%USERPROFILE%\.ssh\hoody-container-1`
    
    2. **Site Manager → New Site:**
       - Protocol: **SFTP**
       - Host: `ssh.us-west-1.containers.hoody.icu`
       - Port: `22`
       - Logon Type: **Key file**
       - User: `root`
       - Key file: (already added above)
    
    3. **Connect** - Two-pane file manager shows local + remote
  
  
  
    **SFTP not natively supported.** Use WinSCP or FileZilla.
    
    Or map WebDAV drive instead (see WebDAV section below).
  


---

### Mount in Linux

```bash
# Install sshfs
sudo apt-get install sshfs  # Debian/Ubuntu
sudo dnf install sshfs      # Fedora
sudo pacman -S sshfs        # Arch

# Create mount point
mkdir -p ~/hoody-containers/container-1

# Mount container
sshfs root@ssh.us-west-1.containers.hoody.icu:/ \
  ~/hoody-containers/container-1 \
  -o IdentityFile=~/.ssh/hoody-container-1

# Access files
ls ~/hoody-containers/container-1/hoody/storage

# Make persistent (add to /etc/fstab)
echo "root@ssh.us-west-1.containers.hoody.icu:/ /home/user/hoody-containers/container-1 fuse.sshfs defaults,IdentityFile=/home/user/.ssh/hoody-container-1,allow_other 0 0" | sudo tee -a /etc/fstab

# Unmount
fusermount -u ~/hoody-containers/container-1
```

---

### SFTP Clients Comparison

| Client | Platform | GUI | Features |
|--------|----------|-----|----------|
| **FileZilla** | Win/Mac/Linux | ✅ | Two-pane, queue, bookmarks, free |
| **WinSCP** | Windows | ✅ | Explorer integration, scripting, sync |
| **Cyberduck** | Mac/Windows | ✅ | Finder integration, cloud services |
| **Transmit** | Mac | ✅ | Beautiful UI, fast, paid |
| **sshfs** | Mac/Linux | ❌ | Command-line, native mounting |
| **Mountain Duck** | Mac/Windows | ❌ | Mount as drive letter, paid |

---

## WebDAV Mounting

**WebDAV provides HTTP-based filesystem access with native OS support.**

### Get Your WebDAV URL


  
    ```bash
    # Get container details to build WebDAV URL
    hoody containers get $CONTAINER_ID

    # The WebDAV URL follows this pattern:
    # https://{project}-{container}-files.{server}.containers.hoody.icu/
    ```
  
  
    ```typescript
    const container = await client.api.containers.get(CONTAINER_ID);
    const { project_id, id, server } = container.data;

    // Construct WebDAV URL from container details
    const webdavUrl = `https://${project_id}-${id}-files.${server.name}.containers.hoody.icu/`;
    console.log(webdavUrl);
    // https://proj123-cont456-files.us-west-1.containers.hoody.icu/
    ```
  
  
    ```bash
    # Get container details to find server name and IDs
    curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID" \
      -H "Authorization: Bearer $TOKEN"

    # Build WebDAV URL from response:
    # https://{project_id}-{container_id}-files.{server_name}.containers.hoody.icu/
    ```
  


**Connection Details:**

```bash
URL: https://{project}-{container}-files.{server}.containers.hoody.icu/
Authentication: Hoody Proxy Permissions
```

**Example URL:**
```
https://proj123-cont456-files.us-west-1.containers.hoody.icu/
```


**Serving path:** WebDAV is served at the root `/` of the files service—clients speak WebDAV verbs (PROPFIND, COPY, MOVE, LOCK, UNLOCK, PROPPATCH, MKCOL) directly against the service root. There is no `/webdav` path suffix.



**Authentication:** WebDAV uses **Hoody Proxy Permissions**, NOT your API token. As part of hoody-kit (not Hoody API), authentication is controlled via [Proxy Permissions](/foundation/proxy/permissions/).

If your container has permissions configured, you'll need those credentials. If permissions are disabled (default), no authentication required.


**You mount FROM your client TO the container** - you control the connection.

---

### Mount in macOS Finder


  
    1. **Finder** → **Go** → **Connect to Server** (⌘K)
    
    2. **Server Address:**
       ```
       https://proj123-cont456-files.us-west-1.containers.hoody.icu/
       ```
    
    3. Click **Connect**
    
    4. **Authentication:**
       - If [Proxy Permissions](/foundation/proxy/permissions/) configured: Use those credentials
       - If no permissions: Leave blank or use any credentials (access is open)
    
    5. Container filesystem mounts as WebDAV drive
    
    **Mounted at:** `/Volumes/webdav/`
  
  
  
    **Add to Login Items for auto-mount:**
    
    1. Mount WebDAV as above
    2. **System Settings** → **General** → **Login Items**
    3. Click **+** and select mounted drive
    4. Auto-mounts on login
  


---

### Mount in Windows Explorer


  
    1. **Right-click "This PC"** → **Map network drive**
    
    2. **Drive letter:** Choose (e.g., `Z:`)
    
    3. **Folder:**
       ```
       https://proj123-cont456-files.us-west-1.containers.hoody.icu/
       ```
    
    4. ✅ **Check:** "Reconnect at sign-in" (for persistence)
    
    5. ✅ **Check:** "Connect using different credentials"
    
    6. **Credentials:**
       - If [Proxy Permissions](/foundation/proxy/permissions/) configured: Use those credentials
       - If no permissions: Leave blank (or any credentials—access is open)
    
    7. Click **Finish** - Drive appears in Explorer as `Z:\`
  
  
  
    **If "The network path was not found":**
    
    1. Enable WebClient service:
       ```powershell
       # Run as Administrator
       sc config webclient start=auto
       sc start webclient
       ```
    
    2. Modify registry for HTTPS support:
       - `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`
       - Set `BasicAuthLevel` = `2` (DWORD)
       - Restart WebClient service
    
    3. Try mapping again
  


---

### Mount in Linux

```bash
# Install davfs2
sudo apt-get install davfs2  # Debian/Ubuntu
sudo dnf install davfs2      # Fedora

# Create mount point
sudo mkdir -p /mnt/hoody-container

# Add credentials to /etc/davfs2/secrets (if Proxy Permissions configured)
echo "https://proj123-cont456-files.us-west-1.containers.hoody.icu/ USERNAME PASSWORD" | sudo tee -a /etc/davfs2/secrets
# OR leave blank if no permissions configured
sudo chmod 600 /etc/davfs2/secrets

# Mount
sudo mount -t davfs https://proj123-cont456-files.us-west-1.containers.hoody.icu/ /mnt/hoody-container

# Access files
ls /mnt/hoody-container/hoody/storage

# Make persistent (add to /etc/fstab)
echo "https://proj123-cont456-files.us-west-1.containers.hoody.icu/ /mnt/hoody-container davfs user,noauto 0 0" | sudo tee -a /etc/fstab

# Unmount
sudo umount /mnt/hoody-container
```

---

### Mount on Android


  
    **Recommended WebDAV client for Android**
    
    1. Install [WebDAV Navigator](https://play.google.com/store/apps/details?id=com.schimera.webdavnav) from Play Store
    
    2. **Add Connection:**
       - Tap **+** → **WebDAV**
       - URL: `https://proj123-cont456-files.us-west-1.containers.hoody.icu/`
       - If Proxy Permissions configured: Enter credentials
       - If no permissions: Leave blank or use any credentials
    
    3. **Browse Files:**
       - Tap connection to browse container filesystem
       - `/hoody/storage`, `/home/user`, etc. all accessible
    
    4. **File Operations:**
       - Download files to device
       - Upload from device to container
       - Create folders, rename, delete
       - Open with Android apps
  
  
  
    **Popular file manager with WebDAV support**
    
    1. Install [Solid Explorer](https://play.google.com/store/apps/details?id=pl.solidexplorer2)
    
    2. **Add Storage:**
       - Menu → Storage → Cloud → WebDAV
       - Server: `proj123-cont456-files.us-west-1.containers.hoody.icu`
       - Path: `/`
       - Protocol: **HTTPS**
       - If permissions: Enter credentials
    
    3. **Access:**
       - Container appears as network storage
       - Two-pane file manager (local + WebDAV)
       - Drag & drop between device and container
  
  
  
    1. Install [FX File Explorer](https://play.google.com/store/apps/details?id=nextapp.fx)
    
    2. **Network → Add Network Location → WebDAV**
       - Full URL: `https://proj123-cont456-files.us-west-1.containers.hoody.icu/`
       - Credentials if needed
    
    3. Browse and manage files like local storage
  


---

### Mount on iOS/iPadOS


  
    **iOS 13+ built-in WebDAV support**
    
    1. Open **Files** app
    
    2. **Tap ••• (More) → Connect to Server**
    
    3. **Server:**
       ```
       https://proj123-cont456-files.us-west-1.containers.hoody.icu/
       ```
    
    4. **Authentication:**
       - If [Proxy Permissions](/foundation/proxy/permissions/) configured: Enter credentials
       - If no permissions: Tap "Connect as Guest"
    
    5. **Container mounts in sidebar** under "Shared"
    
    6. **Access Files:**
       - Browse container filesystem
       - Open files with iOS apps
       - Share files between apps
       - Download/upload via drag & drop
  
  
  
    **Feature-rich file manager with WebDAV**
    
    1. Install [Documents](https://apps.apple.com/app/documents-by-readdle/id364901807)
    
    2. **Services → + → WebDAV Server**
       - Title: "Hoody Container"
       - URL: `https://proj123-cont456-files.us-west-1.containers.hoody.icu/`
       - Credentials if Proxy Permissions configured
    
    3. **Full file management:**
       - Browse, search, preview files
       - Download to device
       - Upload from device or iCloud
       - Zip/unzip files
       - Integrated PDF viewer
  
  
  
    1. Install [FE File Explorer](https://apps.apple.com/app/fe-file-explorer-file-manager/id510282524)
    
    2. **Remote Storage → WebDAV**
       - Server: `proj123-cont456-files.us-west-1.containers.hoody.icu`
       - Path: `/`
       - Protocol: HTTPS
    
    3. Two-pane file manager with thumbnails
  


---

## SFTP vs WebDAV

**Which protocol should you use?**

| Feature | SFTP | WebDAV |
|---------|------|--------|
| **Provided By** | Hoody API (SSH Proxy) | hoody-kit (hoody-files) |
| **Setup** | Requires SSH key | Uses Proxy Permissions |
| **Native Support** | macOS/Linux (via sshfs) | macOS/Windows/iOS (built-in) |
| **Mobile Support** | Android/iOS SSH clients | Android/iOS native file managers |
| **Security** | SSH protocol (very secure) | HTTPS (secure) |
| **Firewall** | Port 22 (sometimes blocked) | Port 443 (rarely blocked) |
| **Speed** | Fast | Slightly slower (HTTP overhead) |
| **Metadata** | Full POSIX support | Limited metadata |
| **Compatibility** | All SFTP clients | All WebDAV clients |

**Recommendation:**
- **SFTP:** When you already have SSH configured and need full POSIX metadata (desktop/laptop)
- **WebDAV:** For native OS mounting, especially on mobile (iOS Files app, Android file managers)
- **Both work equally well** for basic file transfer

---

## Use Cases

### Local Development Workflow

**Mount container → Edit locally → Changes reflected immediately:**

```bash
# Mount container filesystem
# macOS:
open sftp://ssh.us-west-1.containers.hoody.icu

# Edit files in your favorite local editor
code /Volumes/ssh.us-west-1.containers.hoody.icu/hoody/storage/myapp/

# Changes saved locally = changes in container instantly
```

**Perfect for:** Editing code, configs, logs without SSH terminal.

### Backup Container Data

**Drag & drop backup via file manager:**

```bash
# Mount container
# Copy /hoody/storage to local backup
cp -r /Volumes/webdav/hoody/storage ~/Backups/container-backup-2025-11-10/

# Or use rsync for incremental backups
rsync -av /Volumes/webdav/hoody/storage/ ~/Backups/container-latest/
```

**Better than:** Manual file downloads via HTTP API.

### Bulk File Upload

**Upload hundreds of files efficiently:**

```bash
# Mount container WebDAV
# Drag entire project folder from local machine
# to /Volumes/webdav/hoody/storage/projects/

# Or use command-line
cp -r ~/Projects/website/* /Volumes/webdav/var/www/html/
```

**Faster than:** Sequential HTTP uploads.

### View Logs in Real-Time

**Tail logs in your favorite local text editor:**

```bash
# Mount container
# Open log file with live-updating editor (e.g., VS Code, Sublime Text)
code /Volumes/webdav/hoody/storage/myapp/logs/app.log

# Log updates appear in real-time as container writes
```

**Alternative to:** SSH + `tail -f` command.

---

## Best Practices

### 1. Use SFTP for Privacy

SFTP's public key routing means the connection URL doesn't reveal which container you're accessing:

```bash
# Same endpoint for all containers
ssh.us-west-1.containers.hoody.icu

# Routing happens by SSH key (invisible to network observers)
```

WebDAV URLs contain project/container IDs (visible in URL).

### 2. Store Credentials Securely

**SFTP:** SSH keys already in `~/.ssh/` with permissions `600`

**WebDAV:** Use credential managers:
- **macOS:** Keychain stores WebDAV passwords automatically
- **Windows:** Credential Manager saves mapped drive credentials
- **Linux:** davfs2 secrets file with `chmod 600`

**Never hard-code** API tokens in scripts.

### 3. Unmount When Done

Leaving mounts active consumes resources:

```bash
# macOS
umount /Volumes/webdav

# Linux
fusermount -u ~/hoody-containers/container-1

# Windows
net use Z: /delete
```

Or use auto-unmount on logout/shutdown.

### 4. Use Read-Only Mounts for Safety

**SFTP (Linux/macOS):**
```bash
sshfs root@ssh.server.containers.hoody.icu:/ ~/container-1 \
  -o ro,IdentityFile=~/.ssh/key
```

**Prevents accidental deletions** when just browsing/reading files.

### 5. Prefer hoody-files HTTP API for Automation

Local mounting is for **human interaction** (file managers, editors).

For **automation** (scripts, CI/CD), use [Hoody Files HTTP API](/api/files/):

```bash
# ✅ Automation: Direct HTTP
curl "https://...-files.../api/v1/files/data.json"

# ❌ Automation: Mounting unnecessary
mount → access → unmount (slower, more complex)
```

---

## Useful Questions

### Do I need SSH configured for SFTP mounting?

Yes. SFTP uses SSH authentication, so your container must have an `ssh_public_key` configured. See [SSH Access](/foundation/networking/ssh/).

WebDAV doesn't require SSH—it uses [Hoody Proxy Permissions](/foundation/proxy/permissions/) (or no auth if permissions disabled).

### Can I mount multiple containers simultaneously?

Yes! Each container has unique SFTP/WebDAV endpoints. Mount as many as you need.

**SFTP:** Different SSH keys route to different containers (same hostname).

**WebDAV:** Different container URLs mount as different drives.

### Does mounting affect container performance?

Minimal impact. File operations go through hoody-files service, which is optimized for this use case.

**Heavy operations** (copying GBs of data) will consume bandwidth and I/O, like any file transfer.

### Can other users mount my container?

**SFTP:** Only if they have the container's SSH private key.

**WebDAV:** Only if they pass [Proxy Permissions](/foundation/proxy/permissions/) (if configured). If permissions disabled, WebDAV is open access.

**Security:** Configure Proxy Permissions for WebDAV access control. SFTP is always key-protected.

### What happens if I delete files via mounted drive?

Files are **permanently deleted** from container filesystem (same as SSH `rm` command).

**Safety:** Create [snapshots](/foundation/containers/snapshots/) before bulk deletions.

### Does mounting work with containers in "block" network mode?

Yes! Mounting is **INBOUND** (to container) via Hoody Proxy. Network block mode only prevents **OUTBOUND** (from container).

---

## Troubleshooting

### SFTP Connection Refused

**Problem:** "Connection refused" when mounting SFTP

**Solutions:**

1. **Verify container is running:**
   ```bash
   curl "https://api.hoody.icu/api/v1/containers/{id}"
   # Check: "status": "running"
   ```

2. **Test SSH connectivity:**
   ```bash
   ssh -i ~/.ssh/hoody-container-1 root@ssh.server.containers.hoody.icu
   # Should connect to shell
   ```

3. **Check SSH key is added to container:**
   ```bash
   # Verify via API
   GET /api/v1/containers/{id}
   # Check: "ssh_public_key" field is set
   ```

### WebDAV Authentication Failed

**Problem:** Windows can't connect to WebDAV, authentication fails

**Solutions:**

1. **Enable WebClient service:**
   ```powershell
   sc config webclient start=auto
   sc start webclient
   ```

2. **Allow Basic Auth over HTTPS:**
   Registry: `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`
   - Set `BasicAuthLevel` = `2`
   - Restart WebClient

3. **Check Proxy Permissions:**
   - If permissions configured: Verify credentials are correct
   - If no permissions: Any credentials should work (or leave blank)
   - See [Proxy Permissions](/foundation/proxy/permissions/) for configuration

### macOS Won't Connect to "Untrusted" HTTPS

**Problem:** macOS blocks WebDAV connection due to SSL certificate

**Solution:** Hoody uses valid Let's Encrypt certificates—this shouldn't happen.

If it does:
1. Verify URL is correct (use container's actual URL from Hoody)
2. Try SFTP instead (SSH doesn't have this issue)

### Files Appear Outdated After Editing

**Problem:** Changes made in container don't appear in mounted filesystem

**Cause:** File manager caching

**Solutions:**

1. **Unmount and remount:**
   ```bash
   umount /Volumes/webdav
   # Remount
   ```

2. **Refresh view:** F5 or ⌘R in file manager

3. **Use Hoody Terminal** to verify file contents:
   ```bash
   cat /path/to/changed/file
   ```

### Slow Transfer Speeds

**Problem:** File transfers via mounted filesystem are slow

**Solutions:**

1. **Check network latency:**
   ```bash
   ping ssh.server.containers.hoody.icu
   # High latency = slow transfers
   ```

2. **Use local server:** Create container on geographically close server

3. **Compress before transfer:**
   ```bash
   # Instead of copying entire directory
   tar czf backup.tar.gz /source/dir
   # Copy single compressed file (faster)
   ```

4. **Consider direct HTTP upload** for large files:
   ```bash
   curl -X PUT "https://...-files.../api/v1/files/uploads/large-file.zip" \
     --data-binary @large-file.zip
   ```

---

## What's Next

**Other storage capabilities:**
- **[Container Storage →](./)** - Understanding container filesystem and `/hoody/storage`
- **[SQLite Driver →](./sqlite-drive/)** - Concurrent-write-safe databases in `/hoody/databases/`
- **[Cloud Storage →](./cloud/)** - Mount 63 cloud providers via hoody-files
- **[Shared Storage →](./sharing-files/)** - Share directories between containers
- **[/ramdisk →](./ramdisk/)** - Ultra-fast RAM storage

**File access methods:**
- **[Hoody Files API →](/api/files/)** - HTTP-based filesystem operations
- **[SSH Access →](/foundation/networking/ssh/)** - Secure shell for command-line
- **[Hoody Terminal →](/kit/terminals/)** - Web-based shell access

**Understanding gained:**
- ✅ SFTP provided by Hoody API (SSH Proxy infrastructure)
- ✅ WebDAV provided by hoody-files (hoody-kit service)
- ✅ You mount FROM your machine TO container (client-initiated, you control it)
- ✅ Mount container filesystem in macOS Finder, Windows Explorer, Linux
- ✅ SFTP uses SSH keys (privacy-preserving routing via Hoody API)
- ✅ WebDAV uses Proxy Permissions (hoody-kit authentication)
- ✅ Same filesystem access as SSH, just via file manager GUI

---

> **Your container's filesystem, accessible from your local machine.**
> **SFTP via Hoody API. WebDAV via hoody-kit.**

**Client-initiated mounting. Your data, your control. Bridge cloud and local seamlessly.**