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 - HTTP-based filesystem operations
• File Protocols - SFTP/WebDAV backend mounting (as client)

Related Access:

• SSH Access - Secure shell for command-line operations
• Hoody Terminal - Web-based shell (no mounting needed)

---

How It Works

TWO protocols for local mounting:

SFTP

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

WebDAV

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.

Note

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

Note

SSH key required: SFTP uses SSH authentication. Your container must have an ssh_public_key configured. See SSH Access for key generation.

Connection Details

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

Via 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/

Via Terminal

# 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

WinSCP (Recommended)

Download: WinSCP

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

FileZilla

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

Native Windows

SFTP not natively supported. Use WinSCP or FileZilla.

Or map WebDAV drive instead (see WebDAV section below).

---

Mount in Linux

# 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

CLI

# 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/

SDK

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/

HTTP

# 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:

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/

Note

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.

Caution

Authentication: WebDAV uses Hoody Proxy Permissions, NOT your API token. As part of hoody-kit (not Hoody API), authentication is controlled via 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

Via 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 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/

Persistent Mount

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

Map Network Drive

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 configured: Use those credentials
   • If no permissions: Leave blank (or any credentials—access is open)

7. Click Finish - Drive appears in Explorer as Z:\

Troubleshooting

If “The network path was not found”:

1. Enable WebClient service:

   # 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

# 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

WebDAV Navigator

Recommended WebDAV client for Android

1. Install WebDAV Navigator 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

Solid Explorer

Popular file manager with WebDAV support

1. Install Solid Explorer

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

FX File Explorer

1. Install FX File Explorer

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

Files App (Native)

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 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

Documents by Readdle

Feature-rich file manager with WebDAV

1. Install Documents

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

FE File Explorer

1. Install FE File Explorer

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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):

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:

# ✅ 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.

WebDAV doesn’t require SSH—it uses Hoody 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 (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 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:

   curl "https://api.hoody.icu/api/v1/containers/{id}"
   # Check: "status": "running"

2. Test SSH connectivity:

   ssh -i ~/.ssh/hoody-container-1 root@ssh.server.containers.hoody.icu
   # Should connect to shell

3. Check SSH key is added to container:

   # 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:

   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 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:

   umount /Volumes/webdav
   # Remount

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

3. Use Hoody Terminal to verify file contents:

   cat /path/to/changed/file

Slow Transfer Speeds

Problem: File transfers via mounted filesystem are slow

Solutions:

1. Check network latency:

   ping ssh.server.containers.hoody.icu
   # High latency = slow transfers

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

3. Compress before transfer:

   # 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:

   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 → - Concurrent-write-safe databases in /hoody/databases/
• Cloud Storage → - Mount 63 cloud providers via hoody-files
• Shared Storage → - Share directories between containers
• /ramdisk → - Ultra-fast RAM storage

File access methods:

• Hoody Files API → - HTTP-based filesystem operations
• SSH Access → - Secure shell for command-line
• Hoody Terminal → - 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.