The Local Filesystem connector reads and writes files from a directory on the server hosting Univaultport — not from your laptop. This is the connector to pick for on-premise migrations, staging area transfers, and migrations where one side is mounted as an NFS / SMB share on the server.
Step 1 — Identify the server's OS
Three valid path formats depending on where Univaultport runs:
| Server OS | Example absolute path |
|---|---|
| macOS | /Users/you/asset-migrations or /Volumes/external-drive/library |
| Linux | /var/asset-migrations or /mnt/nas/assets |
| Windows | C:\AssetMigrations or \\fileserver\shared\assets |
If you're running Univaultport locally for evaluation, that's your laptop's filesystem. In a hosted setup, it's whichever machine your migration worker runs on.
Step 2 — Confirm the directory exists
The connector requires an absolute path to a directory that:
- Already exists (the connector won't create it)
- Is readable by the user account running the worker process
- Is writable too, if you'll use the connector as a destination
If you're not sure whether the path exists, SSH into the server and:
# macOS / Linux
ls -ld /path/to/your/folder
# Windows PowerShell
Get-Item C:\Path\To\Your\FolderIf the listing fails, fix the path before continuing. The connector's error messages will surface "does not exist or is not readable" but they can't tell you why.
Step 3 — Paste the path into the connector wizard
In the connector setup form:
Root Path
Paste the absolute path. Trim trailing slashes —/data/assets/and/data/assetsmean the same thing. Tildes (~) are expanded to the worker user's home directory.
Click Save & test. Univaultport probes the directory with read+write access and reports back.
Permission cheatsheet
The worker process runs as a specific user — typically nodejs, www-data, or whatever owns the deploy. Make sure that user can access the directory:
macOS / Linux
# Grant your migration user read+write
sudo chown -R nodejs:nodejs /path/to/your/folder
# Or for testing, open it up (avoid in production)
chmod -R 755 /path/to/your/folderWindows
Right-click the folder → Properties → Security → Edit → Add the worker's service account → grant Modify.
Common errors
| Error | Cause | Fix |
|---|---|---|
rootPath "…" does not exist or is not readable | Path doesn't exist on the server, or worker lacks r-x on it | ls -ld <path> on the server; fix ownership/permissions |
rootPath must be an absolute path | You entered a relative path like ./assets | Use the full path starting with / (Unix) or C:\ (Windows) |
EACCES: permission denied (during migration) | Read access works but write access doesn't | chmod u+w or grant the worker user write permission |
ENOSPC: no space left on device | Destination disk is full | Free space, or pick a different volume |
When NOT to use the Local connector
- You want to migrate files from your laptop — the laptop isn't reachable from the server. Use a cloud connector (S3 / GCS / Drive) or a file-transfer connector (FTP / SFTP) instead.
- You want shared access across multiple Univaultport deployments — local paths aren't shared. Mount an NFS / SMB share and treat it as cloud storage, or use S3 as the canonical store.
Performance notes
Local filesystem I/O is typically the fastest connector by a large margin — no API round-trips, no auth, no rate limits. Concurrency is bounded by the disk's IOPS:
- SSD / NVMe: 5+ parallel transfers without contention
- HDD / spinning disk: 2-3 parallel transfers before seek overhead dominates
- NFS / network mount: 1-2 parallel transfers; network latency dominates
The default migration concurrency of 5 works for SSDs. For slower media, the system handles it automatically via back-pressure on the stream.
Next steps
The Local connector is most useful as one side of a pipeline:
- Local → S3 for initial cloud onboarding of on-prem libraries
- Cloudinary → Local for archival snapshots of a DAM
- Local → Local between two folders on the same server (useful for reorganization with
destFolderMode: 'new')
