Skip to content
tapsu01Public

About

Volt is a native SFTP file manager for macOS, built with SwiftUI and libssh2.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

86 Commits

Folders and files

Repository files navigation

Volt

Volt

A native SFTP file manager for macOS, built with SwiftUI and libssh2.

Dual-pane browsing · Secure host-key pinning · Transfer queue · Remote editing

License: MIT Swift 6 macOS 15+ SFTP Security: host-key pinning GitHub release Sponsor on GitHub

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.

Preview

Light Dark
Volt in light appearance Volt in dark appearance

Contents

Highlights

File Management

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

Transfers

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

Authentication

  • Password authentication.
  • SSH private key authentication.
  • SSH agent authentication.
  • Host-key verification with persistent known_hosts pinning.
  • Optional SSH terminal panel for key or agent based sessions.

Requirements

  • 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 that libssh2 is linked against (currently openssl@4), and the packaging scripts bundle exactly that OpenSSL major version.

Install the required libraries:

brew install libssh2

Volt currently builds for the native arm64 or x86_64 architecture of the Mac doing the build. The selected Homebrew libraries must match that architecture.

Quick Start

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

The packaging script automatically:

  • Finds Homebrew at /opt/homebrew or /usr/local.
  • Builds Volt for the selected native architecture.
  • Bundles libssh2, libssl, and libcrypto.
  • 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 Volt

Build Options

Create a DMG in addition to the ZIP archive:

CREATE_DMG=1 ./Scripts/package-app.sh

Build for a specific native architecture:

ARCH=arm64 ./Scripts/package-app.sh

Run the self-use verification flow before using Volt with important VPSes:

./Scripts/verify-self-build.sh

This 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.sh

Without CODE_SIGN_IDENTITY, the script uses an ad-hoc signature. Notarization requires a Developer ID Application certificate and a configured notarytool Keychain profile.

Remote Permissions

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.

Security Model

  • 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 0600 permissions. 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 use 0700.
  • 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.

Development

Build the app during development:

VOLT_LIBSSH2_PREFIX="$(brew --prefix libssh2)" swift build

Run Swift unit tests when using a full Xcode toolchain with XCTest available:

swift test

Run the upload suite with Swift Testing, including on Command Line Tools-only installations:

./Scripts/test-upload.sh

This 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.sh

Check 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.py

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

This 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.sh

Check whether bundled security dependencies need an update:

./Scripts/audit-dependencies.sh

Verify a packaged app bundle:

./Scripts/verify-build.sh build/Volt.app

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

Project Layout

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

Project Status

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.

Security

Please report suspected vulnerabilities privately. See SECURITY.md for the current reporting process.

License

Volt is released under the MIT License. See LICENSE.

Third-party dependency notices are available in Support/THIRD_PARTY_NOTICES.txt.

About

Volt is a native SFTP file manager for macOS, built with SwiftUI and libssh2.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages