A native SFTP file manager for macOS, built with SwiftUI and libssh2.
Dual-pane browsing · Secure host-key pinning · Transfer queue · Remote editing
Volt is a focused macOS file-transfer app for working with local and remote files over SFTP. It provides the familiar dual-pane workflow of a desktop file manager while keeping credentials out of shell command arguments and project configuration files.
| Light | Dark |
|---|---|
- Preview
- Highlights
- Requirements
- Quick Start
- Build Options
- Remote Permissions
- Security Model
- Development
- Project Layout
- Project Status
- Security
- License
- Native SwiftUI interface for macOS.
- Local and remote dual-pane file browser.
- Icon, list, column, and thumbnail-oriented browsing modes.
- Context menus, selection highlighting, sortable metadata columns, and an Inspector sidebar.
- Create, rename, move, duplicate, calculate size, and delete files or folders.
- Multiple tabs that preserve connection state, local path, remote path, open remote edits, and terminal output.
- Upload and download with a visible, cancellable transfer queue.
- Folder upload and folder download support.
- Folder uploads reuse up to four worker sessions, with cancellable background scanning and aggregate byte/file progress. One folder plan is active at a time to bound memory when multiple folders are selected.
- Parallel transfer tuning for larger download workloads.
- Remote editing with a selectable macOS application, followed by explicit upload or discard.
- Configurable permission presets for newly created or uploaded remote items.
Uploads are published from a temporary file in the destination directory, so the SFTP account needs write permission on that directory, not only on the file being replaced. If the directory refuses new files, the server answers Permission denied and Volt names the directory that needs write permission. Replacing an existing file requires the server's POSIX rename extension; Volt reports an error if safe replacement is rejected and never deletes the existing file as a fallback. If the connection is lost during publication, the outcome is reported as unknown and the temporary path is shown for inspection before retrying. There is no automatic retry of an uncertain publish.
Folder upload scanning skips hidden entries and symbolic links and stops above 64 levels, 2,000 directories, or 100,000 entries. Cancellation or failure can leave files that were already successfully published; the queue reports the completed count and refreshes affected directories after the upload batch ends.
- Password authentication.
- SSH private key authentication.
- SSH agent authentication.
- Host-key verification with persistent
known_hostspinning. - Optional SSH terminal panel for key or agent based sessions.
- macOS 15 Sequoia or later.
- Swift 6 with Xcode 16, or matching Command Line Tools.
- Homebrew.
- A native-architecture Homebrew installation of
libssh2. Homebrew pulls in the OpenSSL formula thatlibssh2is linked against (currentlyopenssl@4), and the packaging scripts bundle exactly that OpenSSL major version.
Install the required libraries:
brew install libssh2Volt currently builds for the native arm64 or x86_64 architecture of the
Mac doing the build. The selected Homebrew libraries must match that
architecture.
Clone the repository, build a release app bundle, and open it:
git clone https://github.com/tapsu01/volt.git
cd volt
./Scripts/package-app.sh
open build/Volt.appThe packaging script automatically:
- Finds Homebrew at
/opt/homebrewor/usr/local. - Builds Volt for the selected native architecture.
- Bundles
libssh2,libssl, andlibcrypto. - Rewrites dynamic library install names for app-bundle loading.
- Applies hardened runtime signing when a Developer ID identity is supplied.
- Produces a ZIP archive suitable for distribution.
Generated artifacts:
build/Volt.app
build/Volt-macOS-<architecture>.zip
To run directly through Swift Package Manager:
VOLT_LIBSSH2_PREFIX="$(brew --prefix libssh2)" swift run VoltCreate a DMG in addition to the ZIP archive:
CREATE_DMG=1 ./Scripts/package-app.shBuild for a specific native architecture:
ARCH=arm64 ./Scripts/package-app.shRun the self-use verification flow before using Volt with important VPSes:
./Scripts/verify-self-build.shThis runs the security C tests, dependency audit, release packaging, codesign
verification, bundled dependency hash checks, and runtime library linkage
checks. Without NOTARY_PROFILE, the resulting app is an ad-hoc signed,
self-use-only build for this Mac.
Sign and notarize a distribution build:
CODE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
NOTARY_PROFILE="volt-notary" \
CREATE_DMG=1 \
./Scripts/package-app.shWithout CODE_SIGN_IDENTITY, the script uses an ad-hoc signature.
Notarization requires a Developer ID Application certificate and a configured
notarytool Keychain profile.
Each saved connection can select a permission preset used for newly uploaded or created remote files and folders.
| Preset | Files | Folders | Intended use |
|---|---|---|---|
| Web | 0644 |
0755 |
Publicly readable web assets |
| Private | 0600 |
0700 |
Owner-only files and directories |
| Team | 0660 |
0770 |
Shared group workflows |
Volt reports a warning when a transfer or create operation succeeds but the server refuses the requested permission change.
- SFTP transport and authentication are implemented with libssh2.
- The first connection performs an unauthenticated SSH handshake, displays the SHA-256 host-key fingerprint, and requires explicit confirmation.
- Accepted host keys are stored with
0600permissions. Updates use an inter-process lock, a temporary file,fsync, and atomic replacement. - Changed host keys are rejected before authentication.
- Passwords are kept only in the memory of the current tab and are never written to Keychain, UserDefaults, connection files, or command arguments.
- Saved connection metadata uses
0600; application support and temporary edit directories use0700. - Verify SSH host-key fingerprints outside Volt and keep a server snapshot or backup before large delete, rename, move, or replace operations.
- Connection and host-key probes have a 15-second timeout.
- Downloaded and temporary edit files are created with restrictive permissions.
- Remote directory entries with unsafe or invalid names are skipped before they reach the SwiftUI layer.
- Volt is a high-trust local file manager. Full App Sandbox is intentionally not enabled in this phase because local folder access, security-scoped bookmarks, remote edit temporary files, and external editor selection need a broader design pass.
SSH key or agent authentication is recommended for long-lived server access.
Build the app during development:
VOLT_LIBSSH2_PREFIX="$(brew --prefix libssh2)" swift buildRun Swift unit tests when using a full Xcode toolchain with XCTest available:
swift testRun the upload suite with Swift Testing, including on Command Line Tools-only installations:
./Scripts/test-upload.shThis suite also checks persistent error banners, batch grouping, cancellation, originating-tab context, and remote-edit failure retention. Optional native banner snapshots (320 and 760 points, collapsed and expanded):
VOLT_ERROR_SNAPSHOT_DIR=/tmp/volt-error-snapshots ./Scripts/test-upload.shCheck real authentication and permission errors against an isolated localhost SSH server (requires Homebrew libssh2 and macOS sshd; no saved connections used):
python3 Scripts/test-error-integration.pyRuntime errors appear in a persistent banner under the toolbar. Details shows copyable server/path/error information; Dismiss advances to the next notice. Upload failures in the same batch are grouped. Success and refresh do not clear errors, and explicit cancellation does not create a notice. Unknown upload publish outcomes remain visible for inspection, even after cancellation.
The legacy XCTest suites require full Xcode and emit explicit build warnings when unavailable. The upload suite covers batch completion, tab/connection scope, worker limits, cancellation, traversal limits, and a 10,000-file scan.
Run an isolated localhost SFTP transport benchmark against the earlier revision:
./Scripts/benchmark-upload.py --baseline-commit caffbb6 --files 1000This generates temporary SSH keys and an unprivileged loopback-only sshd,
compares uploaded contents with SHA-256, checks replacement/cancellation,
and writes build/upload-benchmark.json. It measures the C transport driver;
GUI responsiveness, Swift preparation time, and WAN latency are separate checks.
Temporary server processes and keys are removed when the script exits.
Run security-focused C tests for host-key storage, remote entry-name validation, and upload publish failures (including lost replies and cancellation):
./Scripts/test-security.shCheck whether bundled security dependencies need an update:
./Scripts/audit-dependencies.shVerify a packaged app bundle:
./Scripts/verify-build.sh build/Volt.appRelease builds include third-party license files and a
DependencyManifest.json containing dependency versions, architecture, source
provenance, and SHA-256 hashes of the signed dylibs. Builds also include a
BuildInfo.txt file with the Swift toolchain, signing mode, dependency versions,
and dependency hashes used for that app bundle.
See Support/DEPENDENCY_MAINTENANCE.md
for the release maintenance process.
Sources/
CVoltSSH/ C bridge around libssh2 SFTP and host-key operations
Volt/ SwiftUI app, models, views, transfer queue, terminal panel
VoltCore/ Shared Swift core utilities
Tests/
VoltTests/ Swift unit tests
*.c Security-focused C tests
Support/ App metadata, entitlements, icons, notices, maintenance docs
Scripts/ Packaging, security tests, and dependency audit helpers
Volt currently focuses on SFTP. FTP, FTPS, WebDAV, Amazon S3, folder synchronization, and background transfers are not implemented.
The SSH terminal panel is available for key or agent based sessions. SFTP password operations are supported, but password-based interactive SSH terminal sessions are intentionally not used.
Please report suspected vulnerabilities privately. See
SECURITY.md for the current reporting process.
Volt is released under the MIT License. See LICENSE.
Third-party dependency notices are available in
Support/THIRD_PARTY_NOTICES.txt.