AeroFTP

The open-source, multi-protocol file manager for power users.

AeroFTP connects to 23 protocols — from classic FTP/SFTP to Google Drive, Dropbox, OneDrive, MEGA, S3, Azure, GitHub, and more — all from a single desktop app built with Rust and React. The latest addition, GitHub, treats repositories as remote filesystems where every write creates a real Git commit.

Key Features

• 23 Protocols — FTP, FTPS, SFTP, WebDAV, S3, Google Drive, Dropbox, OneDrive, MEGA, Box, pCloud, Azure Blob, 4shared, Filen, Zoho WorkDrive, Internxt, kDrive, Koofr, FileLu, Yandex Disk, OpenDrive, Jottacloud, GitHub
• AeroSync — Smart file synchronization with conflict resolution, scheduling, and bandwidth control
• AeroVault — Military-grade AES-256-GCM-SIV encrypted containers
• AeroAgent — AI-powered file management assistant with 47 tools
• AeroPlayer — Built-in media player with 10-band EQ and WebGL visualizers
• AeroTools — Security toolkit (hashing, encryption, password generation)
• CLI — Full command-line interface with batch scripting support
• 47 Languages — Complete internationalization

Platforms

Links

• GitHub Repository
• Website
• Changelog

Installation

AeroFTP is available for Linux, Windows, and macOS. All packages are built in a clean GitHub Actions CI environment and distributed through GitHub Releases. AeroFTP is free and open-source with no license keys, subscriptions, or telemetry.

Supported Platforms

System Requirements

Note: On Linux, AeroFTP requires the WebKitGTK 4.1 runtime library. Most desktop distributions (Ubuntu, Fedora, Arch with a desktop environment) include it by default. See the Linux installation guide for manual installation commands if needed.

Choose Your Platform

• Linux -- .deb, .rpm, .AppImage, Snap Store, or AUR (Arch)
• Windows -- .msi installer (recommended) or .exe NSIS bundle
• macOS -- .dmg disk image

Downloading

All releases are published on the GitHub Releases page. Each release includes:

• Platform-specific installers and packages
• A changelog describing all changes in the release
• SHA-256 checksums for every artifact

To download the latest version, visit the Releases page and select the appropriate file for your platform and architecture.

Verifying Downloads

All release artifacts are built by GitHub Actions in a reproducible CI environment. To verify the integrity of a downloaded file, compare its SHA-256 checksum against the value published on the Releases page:

# Linux / macOS
sha256sum aeroftp_3.0.1_amd64.deb

# Windows (PowerShell)
Get-FileHash .\AeroFTP_3.0.1_x64-setup.msi -Algorithm SHA256

If the checksum matches the value listed on the GitHub Releases page, the file has not been tampered with during download.

Auto-Update

AeroFTP includes a built-in update checker that runs every 24 hours. When a new version is available, a non-intrusive notification appears with the option to download and install the update.

• AppImage (Linux): Full auto-update support. The app downloads the new AppImage, backs up the current version, replaces it, and restarts automatically.
• Snap (Linux): Updates are handled automatically by the Snap daemon.
• .deb / .rpm (Linux): The app downloads the new package and applies it using Polkit-authenticated system commands.
• Windows / macOS: The app notifies you of the update and provides a download link.

File Associations

AeroFTP registers itself as the handler for .aerovault encrypted container files. Double-clicking an .aerovault file in your operating system's file manager will open it directly in AeroFTP's vault browser.

Next step: Once installed, follow the Quick Start guide to connect to your first server.

Linux Installation

AeroFTP supports all major Linux distributions. Choose the format that best matches your system and preferences.

.deb (Ubuntu / Debian / Linux Mint / Pop!_OS)

Download the .deb package from GitHub Releases and install with apt:

sudo apt install ./aeroftp_3.0.1_amd64.deb

This method automatically resolves and installs any missing dependencies (including WebKitGTK 4.1). Alternatively, use dpkg directly:

sudo dpkg -i aeroftp_3.0.1_amd64.deb
sudo apt-get install -f   # resolve any missing dependencies

To uninstall:

sudo apt remove aeroftp

.rpm (Fedora / RHEL / openSUSE)

Download the .rpm package and install with DNF:

sudo dnf install ./aeroftp-3.0.1-1.x86_64.rpm

Or with RPM directly:

sudo rpm -i aeroftp-3.0.1-1.x86_64.rpm

To uninstall:

sudo dnf remove aeroftp

.AppImage (Universal)

AppImage runs on virtually any Linux distribution without installation. No root access required.

chmod +x AeroFTP_3.0.1_amd64.AppImage
./AeroFTP_3.0.1_amd64.AppImage

The AppImage is fully self-contained and includes all required libraries.

Auto-update: AeroFTP's AppImage has built-in auto-update support. When a new version is available, the app downloads the update, backs up your current AppImage, replaces it in place, and restarts. No manual intervention needed.

Snap Store

Install from the Snap Store with a single command:

sudo snap install aeroftp

The Snap package is published in the stable channel and receives automatic background updates from the Snap daemon. You can also find AeroFTP in the Ubuntu Software Center or GNOME Software.

To check the installed version:

snap info aeroftp

AUR (Arch Linux / Manjaro / EndeavourOS)

AeroFTP is available on the Arch User Repository as aeroftp-bin:

# Using yay
yay -S aeroftp-bin

# Using paru
paru -S aeroftp-bin

The AUR package installs the pre-built binary from GitHub Releases.

Dependencies

AeroFTP on Linux requires the WebKitGTK 4.1 runtime library. Most desktop distributions include it out of the box. If you encounter a missing library error at launch, install it manually:

No other runtime dependencies are required. The application bundles all other libraries internally.

Launch on Startup

AeroFTP can start automatically when you log in. Enable this in Settings > General > Launch on Startup. This creates a standard .desktop autostart entry in ~/.config/autostart/ on freedesktop-compatible desktop environments (GNOME, KDE, XFCE, etc.).

Configuration Data Location

AeroFTP stores its configuration, encrypted vault, chat history, and sync journals in:

~/.config/aeroftp/

To perform a clean uninstall, remove this directory after uninstalling the package.

Next step: Follow the Quick Start guide to connect to your first server.

Windows Installation

AeroFTP provides two distribution formats for Windows 10 and later.

.msi Installer (Recommended)

The MSI installer is the recommended way to install AeroFTP on Windows:

1. Download AeroFTP_3.0.1_x64-setup.msi from GitHub Releases
2. Double-click the .msi file to launch the installer
3. Follow the installation wizard
4. AeroFTP will appear in your Start Menu

The MSI installer:

• Registers file associations (.aerovault encrypted containers)
• Adds a Start Menu shortcut
• Supports standard Add/Remove Programs uninstallation

.exe Portable

For users who prefer not to use the MSI format:

1. Download AeroFTP_3.0.1_x64-setup.exe from GitHub Releases
2. Run the executable directly

Note: The .exe bundle is an NSIS installer that extracts and installs AeroFTP. For a truly portable experience, the AppImage format on Linux is more suitable.

Windows SmartScreen

Since AeroFTP is not signed with a paid Windows code signing certificate, you may see a SmartScreen warning on first launch:

1. Click "More info"
2. Click "Run anyway"

This warning only appears once. The application is built in a clean GitHub Actions CI environment and all release checksums are published on the Releases page.

Launch on Startup

AeroFTP can start automatically with Windows. Enable this in Settings > General > Launch on Startup. This adds a Registry entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run.

Uninstalling

Open Settings > Apps > Installed apps, find AeroFTP, and click Uninstall. Alternatively, use the Add/Remove Programs control panel.

Next step: Follow the Quick Start guide to connect to your first server.

macOS Installation

AeroFTP is distributed as a .dmg disk image for macOS 12 (Monterey) and later.

Installing

1. Download AeroFTP_3.0.1_x64.dmg from GitHub Releases
2. Open the .dmg file
3. Drag AeroFTP into your Applications folder
4. Eject the disk image

Gatekeeper Warning

AeroFTP is not signed with an Apple Developer certificate. On first launch, macOS Gatekeeper will block the application. To allow it:

1. Open System Settings > Privacy & Security
2. Scroll down to the Security section
3. You will see a message: "AeroFTP was blocked from use because it is not from an identified developer"
4. Click "Open Anyway"
5. Confirm by clicking Open in the dialog

Alternatively, you can right-click (or Control-click) the app in Finder and select Open from the context menu. This bypasses Gatekeeper for that specific launch.

Tip: You only need to do this once. After the first launch, macOS will remember your choice.

Apple Silicon

The current release provides an Intel (x64) build. It runs on Apple Silicon (M1/M2/M3/M4) Macs via Rosetta 2 translation. A native ARM64 build may be available in future releases.

Launch on Startup

To start AeroFTP automatically when you log in, enable Settings > General > Launch on Startup inside the app. This registers a macOS Launch Agent.

Uninstalling

Drag AeroFTP from the Applications folder to the Trash. To remove configuration data:

rm -rf ~/Library/Application\ Support/com.aeroftp.AeroFTP
rm -rf ~/Library/Caches/com.aeroftp.AeroFTP

Next step: Follow the Quick Start guide to connect to your first server.

Quick Start

Get connected to your first server in under two minutes. This step-by-step guide walks you through launching AeroFTP, creating an SFTP connection, transferring files, and saving your credentials for future sessions.

1. Launch AeroFTP

After installing AeroFTP, launch it from your application menu, desktop shortcut, or terminal. A splash screen will appear briefly while the application initializes its modules (Tauri runtime, protocol handlers, encryption engine, and IPC bridge).

2. The Connection Screen

Once loaded, you arrive at the connection screen. On a fresh install this area will be empty. After you save servers, their cards will appear here for one-click reconnection.

At the top of the screen you will find the protocol selector -- a categorized grid of all 22 supported protocols. Below the selector are the connection input fields that adapt based on your chosen protocol.

3. Choose a Protocol

Click the protocol selector to expand the full protocol grid. Protocols are organized into distinct categories:

Each protocol card displays a provider logo and name. Hover over a card to see a brief description. Click a card to select it and load the appropriate connection fields.

4. Enter Connection Details (SFTP Example)

For this guide, select SFTP from the Servers category. The connection form will display four fields:

• Host: Enter your server hostname or IP address (e.g., nas.example.com or 192.168.1.100)
• Port: Defaults to 22 for SFTP. Change only if your server uses a non-standard port.
• Username: Your SSH account username
• Password: Your SSH password or key passphrase

Fill in all four fields. If your server uses key-based authentication, AeroFTP will attempt to load your default SSH keys from ~/.ssh/.

Cloud providers: For OAuth-based services like Google Drive or Dropbox, the form shows an Authorize button instead of username/password fields. Clicking it opens your browser to complete the OAuth login flow. No manual credentials are needed.

5. Connect

Click the Connect button. AeroFTP initiates the SSH handshake with the remote server.

First-Time Host Key Verification (SFTP)

When connecting to an SFTP server for the first time, AeroFTP displays a TOFU (Trust On First Use) host key verification dialog. This PuTTY-style dialog shows:

• The server's SHA-256 fingerprint
• The key type (e.g., ED25519, RSA)
• A warning that the host is not yet in your known hosts database

Verify the fingerprint matches your server's actual host key, then click Accept to trust it. The key is stored locally and verified on all subsequent connections. If the key ever changes unexpectedly, AeroFTP will display a prominent MITM warning.

6. You Are Connected

After successful authentication, the dual-pane file manager appears:

• Left panel: Your local filesystem, starting at your home directory
• Right panel: The remote server, starting at your SSH user's home directory

Both panels display files with sortable columns: Name, Size, Date Modified, Type, and Permissions. A breadcrumb path bar at the top of each panel shows your current location.

7. Transfer Files

There are several ways to move files between local and remote:

• Drag and drop: Drag files or folders from one panel to the other
• Double-click: Opens files locally or downloads remote files
• Context menu: Right-click a file and select Upload or Download
• Keyboard: Select files and use the toolbar buttons

During a transfer, a progress bar appears showing:

• Percentage complete
• Transfer speed (MB/s)
• Estimated time remaining (ETA)
• Current file name in batch transfers

8. Save the Connection

After connecting successfully, save your server profile so you can reconnect instantly next time:

1. Navigate to File > Save Connection in the titlebar menu
2. Optionally give the connection a memorable name
3. Click Save

Credentials are stored in AeroFTP's encrypted vault (AES-256-GCM + Argon2id). They never touch your filesystem as plaintext.

9. Reconnect from Saved Servers

Next time you launch AeroFTP, your saved servers appear as cards on the connection screen. Each card displays the server name, protocol badge, and host. Click any card to reconnect instantly with stored credentials.

Right-click a server card for additional options: Edit, Duplicate, Health Check, or Delete.

10. Essential Keyboard Shortcuts

These shortcuts will accelerate your workflow from day one:

What to Explore Next

Now that you are connected, there is much more to discover:

• Interface Overview -- Detailed tour of every UI element
• AeroSync -- Intelligent directory synchronization with conflict resolution
• AeroVault -- Military-grade encrypted file containers
• AeroAgent -- AI assistant with 47 tools for file management and code analysis
• AeroTools -- Integrated code editor (Monaco), terminal, and development tools
• Protocols Overview -- Guide to all 22 supported protocols

Next step: Read the Interface Overview to understand every panel, menu, and shortcut available in AeroFTP.

Interface Overview

AeroFTP uses a dual-pane file manager layout with an integrated development toolkit, a VS Code-style titlebar, and extensive keyboard-driven navigation. This page provides a detailed tour of every area of the interface.

Titlebar and Menus

The titlebar replaces the native window decoration with a custom VS Code-style design. It contains four dropdown menus that open on click and switch on hover:

To the right of the menus you will find:

• AeroFile toggle: Switches to local-only file manager mode (no remote panel)
• Settings gear: Opens the Settings dialog
• Theme toggle: Cycles through Light, Dark, Tokyo Night, and Cyber themes
• Window controls: Minimize, maximize, and close buttons

Dual-Pane File Manager

The core workspace is divided into two resizable panels separated by a draggable divider.

Left Panel (Local)

Displays your local filesystem. Features include:

• Tabbed browsing: Up to 12 local path tabs, each pointing to a different directory. Drag tabs to reorder them. Middle-click a tab to close it.
• Breadcrumb navigation: Click any segment of the path to jump to that directory
• Column sorting: Click any column header (Name, Size, Date Modified, Type, Permissions) to sort ascending or descending
• Inline rename: Press F2 or click on an already-selected filename to rename it in place

Right Panel (Remote)

Displays the remote server or cloud provider's filesystem. Appears after establishing a connection. Supports the same column layout, sorting, and breadcrumb navigation as the local panel.

AeroFile mode: Toggle from the View menu to hide the remote panel entirely and use AeroFTP as a standalone local file manager with all its features (tags, preview, compression, encryption).

Session Tabs

When connected to multiple servers simultaneously, each connection appears as a session tab above the remote panel. The active tab is highlighted; inactive tabs show the server name and protocol icon.

• Right-click a tab to access: Close Tab, Close Other Tabs, Close All Tabs
• Middle-click a tab to close it immediately
• Each tab maintains its own remote path state independently

Places Sidebar

The left sidebar provides quick navigation organized into collapsible sections:

File List and Columns

Both panels display files in a table with these columns:

All columns are sortable by clicking the header. The current sort direction is indicated by an arrow icon.

Context Menus

Right-click any file or folder to open a comprehensive context menu with operations relevant to the selection and current protocol:

• File operations: Open, Rename (F2), Delete, Move, Copy, Cut/Paste
• Transfer: Upload or Download (depending on which panel)
• Compression: Create ZIP, 7z, TAR, GZ, XZ, or BZ2 archives. Password-protected ZIP and 7z supported.
• Encryption: Encrypt files or folders into AeroVault containers
• Tags: Assign color labels from a submenu of 7 preset colors, or clear all tags
• Cloud-specific: Star/unstar (Google Drive), Tags (Box/Dropbox), Labels (Zoho WorkDrive), Trash management
• AI: "Ask AeroAgent" sends the selected file's context to the AI assistant for analysis

Status Bar

The bottom bar displays real-time connection and application state:

• Protocol badge: Shows the active protocol (FTP, SFTP, S3, Google Drive, etc.)
• Host information: Server hostname and port
• Remote path: Current directory path on the remote server
• Storage quota: Used/total storage when supported by the provider (e.g., Google Drive, Dropbox)
• AI status widget: Compact indicator showing AeroAgent state -- Ready, Thinking, Running tool, or Error

AeroTools Panel

Toggle AeroTools from the View menu, the titlebar button, or Ctrl+Shift+E. A resizable bottom panel slides up with three tabs:

Command Palette

Press Ctrl+Shift+P to open the Command Palette -- a VS Code-style quick-access overlay with approximately 25 commands organized into five categories. Type to filter, use arrow keys to navigate, and press Enter to execute.

Themes

AeroFTP ships with four carefully designed themes. Cycle through them with the theme toggle button in the titlebar, or select a specific theme from View > Theme.

Keyboard Shortcuts Reference

Next step: Learn about the protocols AeroFTP supports, or dive into features like AeroSync, AeroVault, and AeroAgent.

Protocol Overview

AeroFTP supports 23 protocols and cloud storage providers natively. Each protocol is implemented in Rust with full streaming support, credential encryption via the OS keyring, and integration with AeroSync, AeroAgent, and the CLI.

Protocol Comparison

Server Protocols (5)

OAuth Cloud Providers (7)

Direct Auth Cloud Providers (10)

Developer Platform (1)

Protocol Categories

Server Protocols (Self-Hosted)

These connect to servers you control. You provide the hostname, port, and credentials.

• FTP -- Traditional unencrypted file transfer. Suitable for legacy servers and shared hosting on trusted networks.
• FTPS -- FTP secured with TLS/SSL. Supports both Explicit (STARTTLS on port 21) and Implicit (port 990) modes. AeroFTP detects TLS downgrade attempts and warns the user.
• SFTP -- Secure file transfer over SSH. The recommended choice for self-hosted servers. Supports password and SSH key authentication with TOFU host key verification.
• WebDAV -- HTTP-based file access over HTTPS. Used by Nextcloud, Seafile, and many NAS devices. Supports Basic and Digest authentication.
• S3-Compatible -- Object storage using the S3 API. Works with AWS, Wasabi, Backblaze B2, and any S3-compatible endpoint.

OAuth Cloud Providers

These authenticate through the provider's OAuth2 PKCE flow. AeroFTP opens a browser window for authorization and stores tokens securely in the vault.

• Google Drive, Dropbox, OneDrive, Box, pCloud, Zoho WorkDrive, Koofr

Direct Auth Cloud Providers

These use API keys, email/password, session tokens, or personal access tokens directly. No browser-based OAuth flow is required.

• MEGA -- Zero-knowledge E2E encryption with client-side AES.
• Azure Blob -- Enterprise object storage with HMAC signing or SAS tokens.
• 4shared -- OAuth 1.0 with HMAC-SHA1 signing (RFC 5849).
• Filen -- E2E encrypted with PBKDF2 key derivation and AES-256-GCM. Optional 2FA.
• Internxt -- E2E encrypted with PBKDF2 + BIP39 mnemonic and AES-256-CTR.
• kDrive -- Infomaniak cloud storage with API token authentication.
• Jottacloud -- Norwegian cloud with Personal Login Token authentication.
• FileLu -- API key authentication with file password protection and privacy controls.
• Yandex Disk -- OAuth2 token-based access to Yandex cloud storage.
• OpenDrive -- Session-based authentication with MD5 checksums and zlib compression.

Developer Platform

• GitHub -- Repository file browser and manager. Supports OAuth2, Personal Access Tokens (PAT), and GitHub App .pem key authentication. Browse, download, upload, and delete files across unlimited repositories.

WebDAV Presets

AeroFTP includes pre-configured WebDAV presets for popular services:

When using a WebDAV preset, AeroFTP automatically configures the endpoint path. You only need to provide your server hostname and credentials.

S3-Compatible Presets

AeroFTP supports any S3-compatible service. Built-in presets auto-configure the endpoint and region:

For Cloudflare R2, a dedicated Account ID field is shown in the connection form. The endpoint is computed automatically from the account ID.

Feature Matrix

Trash Management

Not all providers expose a trash/recycle bin API. The following table shows which protocols support trash operations in AeroFTP:

File Versioning

Share Links

Tags and Labels

Integration Compatibility

AeroSync

All 23 protocols are supported by AeroSync for bidirectional synchronization. Server protocols (FTP, FTPS, SFTP, WebDAV, S3) and all cloud providers can be used as sync targets via the AeroCloud background sync engine.

AeroSync features available across all protocols:

• Bidirectional and unidirectional sync
• Conflict resolution (keep local, keep remote, keep newer, skip)
• Sync profiles (Mirror, Two-way, Backup, Pull, Remote Backup)
• Transfer journal with checkpoint/resume
• Post-transfer verification (size, mtime, SHA-256)
• Configurable retry with exponential backoff
• Bandwidth throttling
• Dry-run mode with export

CLI Support

All 23 protocols are accessible from the aeroftp-cli command-line tool using URL-based connections:

aeroftp ls sftp://user@myserver.com/path/
aeroftp get s3://mybucket/file.txt
aeroftp put ftp://user@host/upload/ ./local-file.txt
aeroftp sync ftp://user@host/ ./local-dir/
aeroftp tree webdav://user@nextcloud.example.com/remote.php/dav/files/user/

The CLI supports 13 commands (connect, ls, get, put, mkdir, rm, mv, cat, find, stat, df, tree, sync), batch scripting via .aeroftp files, glob pattern transfers, and --json output for automation.

AeroAgent server_exec

AeroAgent can execute file operations on saved servers through the server_exec tool. This tool resolves credentials from the vault in Rust and never exposes passwords to the AI model.

The server_exec tool supports 10 operations: ls, cat, get, put, mkdir, rm, mv, stat, find, and df. Server names are matched with fuzzy matching against saved server profiles.

FTP / FTPS

FTP (File Transfer Protocol) is the original file transfer protocol, dating back to 1971 and standardized in RFC 959. Despite its age, FTP remains the default protocol for web hosting providers, embedded devices, and legacy enterprise systems. AeroFTP provides a modern FTP/FTPS client built on the suppaftp library with full TLS support, automatic feature detection, and transfer resumption.

Connection Settings

When you select a saved FTP server, all fields are populated from the encrypted credential store. The password is never written to disk in plaintext.

Encryption Modes

AeroFTP offers three encryption options. Choosing the right one depends on your server configuration.

None (Plain FTP) -- Not Recommended

• Port: 21
• Security: Zero encryption. Username, password, and all file data are transmitted in cleartext.
• Use case: Local network testing, isolated lab environments, or legacy hardware that does not support TLS.

Warning: Never use plain FTP over the public internet. Your credentials can be captured by anyone on the network path. AeroFTP does not prevent you from connecting without encryption, but you should treat this mode as inherently insecure.

Explicit TLS (AUTH TLS) -- Recommended

• Port: 21
• Security: The connection begins as plain FTP on port 21, then AeroFTP sends the AUTH TLS command to upgrade the control channel to TLS. The data channel is also encrypted via PROT P.
• Use case: The vast majority of hosting providers, cPanel, Plesk, and any modern FTP server.

This is the most compatible secure option. The initial handshake is unencrypted (just enough to negotiate TLS), after which all traffic -- including credentials -- is encrypted. Most shared hosting providers configure Explicit TLS by default.

Implicit TLS (FTPS on port 990)

• Port: 990
• Security: TLS is established immediately on connection, before any FTP commands are exchanged. There is no plaintext phase.
• Use case: Enterprise and government environments that require encryption from the first byte. Some banking and compliance-focused servers mandate this mode.

Implicit TLS is less common than Explicit TLS but provides a marginally stronger guarantee because no unencrypted bytes ever cross the wire.

TLS Downgrade Detection

If you select Explicit TLS (if available) and the server rejects the AUTH TLS command, AeroFTP does not silently fall back to plain FTP. Instead, it:

1. Flags the connection internally as tls_downgraded
2. Logs a security warning with the server's response
3. Continues the connection over plain FTP so you can still access your files
4. Displays a visible security indicator so you know the session is unencrypted

This prevents a class of attack where a man-in-the-middle strips the TLS upgrade. You will always know when your connection is not encrypted.

Feature Detection (FEAT / MLSD / MLST)

When AeroFTP connects to an FTP server, it sends the FEAT command to discover the server's capabilities. This determines which features are available:

• MLSD (Machine Listing of a Directory): Returns structured, machine-parseable directory listings with precise file metadata -- size, modification time, type, and permissions. AeroFTP prefers MLSD over the older LIST command whenever available.
• MLST (Machine Listing of a Single File): Retrieves metadata for a single file without listing the entire directory. Used for efficient file existence checks and stat operations.
• REST STREAM: Indicates support for transfer resumption (see below).
• UTF8: Enables UTF-8 filename encoding, which AeroFTP activates automatically when supported.

If the server does not support FEAT (very old servers), AeroFTP falls back to LIST and parses the Unix-style or Windows-style directory output heuristically.

Passive Mode

All AeroFTP FTP connections use passive mode (PASV) exclusively. In passive mode, the client initiates both the control and data connections to the server, which works reliably behind NAT routers and firewalls.

AeroFTP does not support active mode (PORT), where the server connects back to the client. Active mode requires inbound firewall rules on the client side and is incompatible with most consumer and corporate networks.

Firewall Note: Even in passive mode, the server must have a range of ports open for data connections (typically configured in the FTP server as a passive port range, e.g. 49152-65535). If directory listings succeed but file transfers fail, the passive port range is likely blocked.

Transfer Resumption

AeroFTP supports resuming interrupted transfers using the FTP REST (Restart) command. If a download or upload is interrupted by a network error:

• Downloads: AeroFTP sends REST <offset> before RETR to skip bytes already received, then appends to the partial local file.
• Uploads: AeroFTP queries the server for the partial file size and resumes with REST <offset> before STOR.

Resume is only available if the server advertises REST STREAM via FEAT. Most modern FTP servers support this.

Server Compatibility

AeroFTP is tested with the following FTP servers:

CLI Usage

The AeroFTP CLI supports FTP connections using URL syntax:

# List files on an FTP server with Explicit TLS
aeroftp ls ftp://user@ftp.example.com/ --tls explicit

# Download a file
aeroftp get ftp://user@ftp.example.com/public_html/index.html ./

# Upload a file
aeroftp put ftp://user@ftp.example.com/public_html/ ./style.css

# Recursive directory listing
aeroftp tree ftp://user@ftp.example.com/public_html/ -d 3

# Sync local directory to remote
aeroftp sync ftp://user@ftp.example.com/public_html/ ./website/ --direction push

The --tls flag accepts none, explicit, or implicit. If omitted, AeroFTP defaults to explicit.

For servers with self-signed certificates, add --insecure to skip certificate validation.

Common Issues

SFTP

SFTP (SSH File Transfer Protocol) provides encrypted file transfer over an SSH channel. Unlike FTP/FTPS, which layer encryption on top of a separate protocol, SFTP runs entirely within SSH -- there is a single encrypted connection for both commands and data. This makes SFTP the recommended protocol for connecting to Linux servers, Unix systems, NAS devices, and any host running an SSH daemon.

AeroFTP's SFTP implementation is built on the russh library (v0.57), supporting modern key exchange algorithms, host key verification, and streaming transfers with no file size limit.

Connection Settings

Authentication Methods

AeroFTP supports two authentication methods, attempted in order of priority:

1. Key-Based Authentication (Recommended)

If a private key path is provided, AeroFTP uses it to authenticate. This is the most secure method and is standard practice for production servers.

• Supported key types: Ed25519, RSA (2048/4096-bit), ECDSA (P-256, P-384)
• Passphrase-protected keys: Fully supported. AeroFTP prompts for the passphrase when the key is loaded.
• Key file formats: OpenSSH format (-----BEGIN OPENSSH PRIVATE KEY-----) and PEM format are both accepted.

Recommendation: Ed25519 keys are preferred over RSA for both security and performance. Generate one with: ssh-keygen -t ed25519 -C "your@email.com"

2. Password Authentication

Standard username and password login. The password is transmitted over the encrypted SSH channel, so it is never exposed on the network. However, key-based authentication is preferred because it eliminates the risk of brute-force attacks.

TOFU Host Key Verification

On the first connection to a new server, AeroFTP displays a Trust On First Use (TOFU) dialog modeled after PuTTY's host key verification prompt.

The dialog displays:

• Server hostname and port: So you can verify you are connecting to the intended host.
• Key algorithm: Ed25519, RSA, or ECDSA.
• SHA-256 fingerprint: The cryptographic hash of the server's public key, displayed in hexadecimal. You can compare this against the fingerprint shown by ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server.
• MITM warning: A clear explanation that accepting an unverified key carries risk.

Once you accept the host key, AeroFTP stores it locally. On all subsequent connections:

• If the server presents the same key, the connection proceeds silently.
• If the server presents a different key, AeroFTP displays a prominent warning indicating a potential man-in-the-middle attack. You must explicitly accept the new key before connecting.

This behavior mirrors how OpenSSH's known_hosts file works, but with a graphical interface instead of a terminal prompt.

Symlink Directory Detection

AeroFTP follows symbolic links and correctly identifies symlinked directories. When listing a directory, AeroFTP calls sftp.metadata() on each symlink target to determine whether it points to a file or a directory.

This is critical for NAS devices that use symlinks extensively:

• Synology DiskStation: Shared folders under /volume1/ are often symlinked from user home directories.
• WD MyCloud: Network shares may appear as symlinks in the SFTP filesystem.
• QNAP: Similar symlink patterns for shared folders.

Without symlink resolution, directories would appear as files and could not be browsed. AeroFTP handles this transparently.

File Permissions

AeroFTP displays full Unix file permissions in the PERMS column of the file list:

• Permissions are shown in the standard rwxrwxrwx format (owner / group / others).
• The PERMS column is sortable and responsive -- it hides on narrow viewports to save space.
• Permission values are read directly from the SFTP server's file attributes.

Note: AeroFTP displays permissions but does not currently provide a GUI to change them. Use the AeroAgent shell_execute tool or an SSH terminal for chmod operations.

Large File Transfers

SFTP transfers are fully streaming -- files are read and written in chunks without loading the entire file into memory. There is no practical file size limit beyond what the server's filesystem supports.

• Downloads: Data is streamed from the server and written to disk in chunks.
• Uploads: Data is read from disk and streamed to the server.
• Resume: If a transfer is interrupted, AeroFTP can resume from the last byte by seeking to the appropriate offset in the remote file.

CLI Usage

The AeroFTP CLI supports SFTP connections with password or key-based authentication:

# Connect with password (prompted interactively)
aeroftp ls sftp://user@myserver.com/

# Connect with a specific port
aeroftp ls sftp://user@myserver.com:2222/home/user/

# List files with details
aeroftp ls sftp://user@myserver.com/ -l

# Download a file
aeroftp get sftp://user@myserver.com/var/log/syslog ./

# Upload a file
aeroftp put sftp://user@myserver.com/home/user/docs/ ./report.pdf

# Key-based authentication
aeroftp ls sftp://user@myserver.com/ --key /home/user/.ssh/id_ed25519

# Key with passphrase
aeroftp ls sftp://user@myserver.com/ --key /home/user/.ssh/id_rsa --key-passphrase "my passphrase"

# Recursive directory tree
aeroftp tree sftp://user@myserver.com/var/www/ -d 3

# Sync local to remote
aeroftp sync sftp://user@myserver.com/var/www/html/ ./website/ --direction push

Common Issues

Tips

• For NAS devices, always verify the SSH port in the NAS administration interface. Synology uses port 22 by default, but this can be changed.
• Ed25519 keys are recommended over RSA for both security and connection speed.
• SFTP is the best protocol for AeroSync when connecting to self-hosted servers, as it provides encryption, reliable file metadata (size, mtime, permissions), and transfer resumption.
• If you see "Permission denied" errors, verify that the SSH user has read/write access to the target directory with ls -la on the server.

WebDAV

WebDAV (Web Distributed Authoring and Versioning) extends HTTP with file management operations defined in RFC 4918. It is the standard remote file access protocol used by Nextcloud, Seafile, CloudMe, and many NAS devices. Because WebDAV runs over HTTP/HTTPS, it works through corporate firewalls and proxies that block other protocols.

AeroFTP's WebDAV implementation uses the reqwest HTTP client with quick-xml for parsing PROPFIND responses, supporting both Basic and Digest authentication, TLS certificate validation, and streaming uploads.

Connection Settings

Presets

AeroFTP includes preconfigured presets that auto-fill the endpoint path and port for popular WebDAV services. Select a preset from the dropdown, fill in your credentials, and connect.

Nextcloud Setup

Nextcloud is the most common WebDAV use case. To connect:

1. Select the Nextcloud preset.
2. Enter your Nextcloud server hostname (e.g. cloud.example.com).
3. Replace USERNAME in the path with your exact Nextcloud login name (case-sensitive).
4. For the password, generate an app password in Nextcloud: go to Settings > Security > Devices & sessions and create a new app password.

Important: Do not use your main Nextcloud password if you have 2FA enabled -- it will be rejected. App passwords bypass 2FA and are the recommended authentication method.

Seafile Setup

Seafile uses the SeafDAV extension for WebDAV access:

1. Select the Seafile preset (path auto-fills to /seafdav).
2. Enter your Seafile server hostname.
3. Use your Seafile account credentials.

Note: SeafDAV must be enabled by the Seafile server administrator. Check seahub_settings.py for ENABLE_WEBDAV_SECRET. If it is not enabled, you will receive a 404 error on the WebDAV endpoint.

CloudMe Setup

CloudMe provides direct WebDAV access at webdav.cloudme.com:

1. Select the CloudMe preset.
2. The host is auto-filled to webdav.cloudme.com.
3. Enter your CloudMe username and password.
4. 3 GB of free storage is available.

Root Boundary Enforcement

AeroFTP enforces a root boundary based on the configured WebDAV path. This means:

• Navigation is restricted to the initial path and its subdirectories.
• The cd() and cd_up() operations cannot navigate above the configured path.
• This prevents accidental access to other users' directories on multi-tenant servers.

For example, if you connect with path /remote.php/dav/files/alice/, you cannot navigate to /remote.php/dav/files/bob/ even if the server would allow it. The root boundary is enforced client-side by AeroFTP.

Authentication Methods

AeroFTP supports two HTTP authentication schemes for WebDAV:

Basic Authentication

The default method. Username and password are sent as a Base64-encoded header on each request. When used over HTTPS (recommended), this is secure because the entire HTTP conversation is encrypted.

Digest Authentication (RFC 2617)

Some WebDAV servers require Digest authentication, where the password is never sent over the wire -- instead, a hash-based challenge-response mechanism is used. AeroFTP auto-detects Digest authentication when the server responds with a 401 Unauthorized and a WWW-Authenticate: Digest header, then automatically switches to the Digest scheme.

You do not need to configure this manually. AeroFTP handles the detection and switching transparently.

Features

• PROPFIND: Directory listings are retrieved using the WebDAV PROPFIND method with Depth: 1. AeroFTP parses the XML response to extract file names, sizes, modification times, and content types.
• TLS: All HTTPS connections use the system's certificate store for validation. Self-signed certificates trigger a confirmation dialog before proceeding.
• Streaming uploads: Large files are uploaded using chunked transfer encoding, so they are streamed from disk without loading the entire file into memory.
• Create directories: The MKCOL method is used to create new directories on the server.
• Delete: The DELETE method removes files and directories (recursively for directories).
• Move/Rename: The MOVE method with a Destination header handles both moves and renames.

CLI Usage

The AeroFTP CLI supports WebDAV connections using URL syntax:

# Nextcloud -- list files
aeroftp ls webdav://user@cloud.example.com/remote.php/dav/files/user/

# Nextcloud -- download a file
aeroftp get webdav://user@cloud.example.com/remote.php/dav/files/user/Documents/report.pdf ./

# Nextcloud -- upload a file
aeroftp put webdav://user@cloud.example.com/remote.php/dav/files/user/Documents/ ./notes.txt

# CloudMe -- list root
aeroftp ls webdav://user@webdav.cloudme.com/

# Custom WebDAV server on HTTP (non-TLS)
aeroftp ls webdav://user@nas.local:5005/webdav/share/ --insecure

# Directory tree
aeroftp tree webdav://user@cloud.example.com/remote.php/dav/files/user/ -d 3

# JSON output
aeroftp ls webdav://user@cloud.example.com/remote.php/dav/files/user/ -l --json

Passwords are prompted interactively. For saved connections, use --profile "My Nextcloud" instead of URL mode.

Common Issues

Tips

• For Nextcloud, always generate an app password. This is the officially recommended method and avoids issues with 2FA, rate limiting, and account lockout policies.
• WebDAV performance depends heavily on the server. For directories with many files, SFTP is significantly faster because it avoids the XML parsing overhead.
• When using AeroSync with WebDAV, the size + modification time compare mode is recommended. WebDAV servers do not consistently provide checksums, and the getlastmodified property may have only second-level precision.
• For NAS devices (Synology, QNAP) that offer both WebDAV and SFTP, prefer SFTP for better performance and more reliable file metadata.
• CloudMe's free tier (3 GB) is one of the few remaining free WebDAV services that works without any server-side configuration.

S3-Compatible Storage

AeroFTP supports Amazon S3 and any S3-compatible object storage service. The S3 protocol has become the de facto standard for cloud object storage, and dozens of providers offer compatible APIs. AeroFTP includes built-in presets for 10 major providers with automatic endpoint configuration, plus support for any custom S3-compatible endpoint including self-hosted MinIO.

Connection Settings

When you select a provider from the preset dropdown, the endpoint and available regions are populated automatically. For providers with multiple regions (AWS, Wasabi, DigitalOcean), a region selector appears. Selecting a region computes the final endpoint URL from the template.

Provider Presets

AeroFTP includes 10 preconfigured S3 presets. Each preset defines an endpoint URL template where {region} is replaced with your selected region.

Cloudflare R2

Cloudflare R2 uses your Account ID instead of a traditional region. AeroFTP provides a dedicated Account ID input field for R2 connections.

The endpoint is computed automatically from your Account ID:

{your-account-id}.r2.cloudflarestorage.com

To generate R2 API tokens:

1. Go to the Cloudflare Dashboard.
2. Navigate to R2 > Overview > Manage R2 API Tokens.
3. Create a token with "Object Read & Write" permissions for your target bucket.
4. Copy the Access Key ID and Secret Access Key into AeroFTP.

R2 has no egress fees, making it ideal for content delivery and backup workloads where you read data frequently.

MinIO (Self-Hosted)

For MinIO and other self-hosted S3-compatible servers:

1. Select MinIO from the provider dropdown (or leave it on Custom).
2. Enter your MinIO server URL as the endpoint (e.g. http://minio.local:9000 or https://s3.internal.company.com).
3. Use your MinIO access key and secret key (configured in the MinIO console or via mc admin user).
4. Leave the region blank or set it to us-east-1 (MinIO defaults).

Path-Style vs Virtual-Hosted-Style Addressing

S3 supports two URL styles for accessing objects:

• Path-style: https://endpoint/bucket/key -- the bucket name is part of the URL path.
• Virtual-hosted-style: https://bucket.endpoint/key -- the bucket name is a subdomain.

AeroFTP uses path-style addressing by default, which is compatible with all S3 providers including MinIO, Ceph, and other self-hosted solutions. AWS has been deprecating path-style for its own service, but path-style continues to work and is the only option for non-AWS endpoints.

Multipart Upload

For files larger than a configurable threshold, AeroFTP uses S3's multipart upload API:

1. Initiate: AeroFTP starts a multipart upload session and receives an upload ID.
2. Upload parts: The file is split into parts (typically 5-100 MB each) and uploaded individually. Each part receives an ETag for integrity verification.
3. Complete: AeroFTP sends the list of part ETags to finalize the upload. S3 assembles the parts into the final object.

Multipart upload provides several benefits:

• Resumability: If a part fails, only that part needs to be re-uploaded.
• Parallelism: Multiple parts can be uploaded concurrently for faster throughput.
• Large file support: Single-part uploads are limited to 5 GB on AWS; multipart supports up to 5 TB.

Pagination

S3 bucket listings are paginated using continuation tokens. AeroFTP handles this transparently -- it fetches all pages automatically when listing a directory, even for buckets containing millions of objects. The continuation token loop was hardened in v2.4.0 to prevent infinite loops on malformed responses.

CLI Usage

The AeroFTP CLI supports S3 connections using URL syntax with embedded credentials:

# List bucket contents
aeroftp ls s3://AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI@s3.us-east-1.amazonaws.com --bucket my-bucket

# List with a specific region
aeroftp ls s3://key:secret@s3.eu-west-1.amazonaws.com --bucket data-eu -l

# Download a file
aeroftp get s3://key:secret@s3.us-east-1.amazonaws.com --bucket my-bucket /reports/2024.pdf ./

# Upload a file
aeroftp put s3://key:secret@s3.us-east-1.amazonaws.com --bucket my-bucket / ./backup.tar.gz

# MinIO (custom endpoint)
aeroftp ls s3://minioadmin:minioadmin@minio.local:9000 --bucket backups /

# Cloudflare R2
aeroftp ls s3://key:secret@ACCOUNT_ID.r2.cloudflarestorage.com --bucket assets /

# Show bucket storage usage
aeroftp df s3://key:secret@s3.us-east-1.amazonaws.com --bucket my-bucket

# JSON output for scripting
aeroftp ls s3://key:secret@endpoint --bucket name / --json

Security note: Embedding credentials in URLs is convenient for scripting but exposes them in shell history. For production use, save the connection as a profile in the AeroFTP GUI and use --profile "My S3" instead.

Common Issues

Tips

• S3 does not have a traditional directory structure. AeroFTP emulates folders using / prefix delimiters, which is the standard convention across all S3 tools.
• When editing a saved S3 connection, the endpoint is auto-resolved from the provider registry if it was not stored previously. This ensures backward compatibility with connections saved in older AeroFTP versions.
• For AeroSync with S3, use the size compare mode. S3 objects do not have traditional modification times -- the LastModified timestamp reflects when the object was written to S3, not the original file's mtime.
• Backblaze B2 and Cloudflare R2 both offer free tiers with no egress fees, making them excellent choices for backup and archival workloads.

Google Drive

AeroFTP connects to Google Drive via the official Google Drive API v3 with OAuth2 authentication. You can browse, upload, download, and manage files on your personal Google Drive and shared (team) drives as if they were a remote filesystem. AeroFTP supports starring, comments, custom properties, file versioning, trash management, and storage quota display.

Connection and Authentication

Authentication is handled entirely through OAuth2 -- there are no manual tokens or API keys to configure.

Setup Steps

1. In the AeroFTP connection screen, select Google Drive from the protocol list.
2. Click Connect. Your default browser opens to Google's OAuth consent screen.
3. Sign in with your Google account (or select an already signed-in account).
4. Review the permissions and click Allow. AeroFTP requests access to your Google Drive files.
5. The browser redirects back to AeroFTP with an authorization code. This is captured automatically -- you do not need to copy or paste anything.
6. AeroFTP exchanges the authorization code for access and refresh tokens, which are stored encrypted in the OS keyring.

Token refresh is automatic. When the access token expires (typically after 1 hour), AeroFTP uses the refresh token to obtain a new one without any user interaction.

Custom OAuth Credentials

By default, AeroFTP uses its own OAuth client for Google Drive. If you prefer to use your own Google Cloud project credentials (for higher API quotas or organizational policies), you can enter a custom Client ID and Client Secret in Settings > Cloud Providers > Google Drive.

To create your own credentials:

1. Go to the Google Cloud Console.
2. Create a project and enable the Google Drive API.
3. Under Credentials, create an OAuth 2.0 Client ID of type "Desktop app".
4. Copy the Client ID and Client Secret into AeroFTP's settings.

File Browsing

Once connected, your Google Drive appears as a file tree. The root / shows your My Drive contents. Navigation works the same as any other protocol -- double-click folders to enter, use the breadcrumb bar to go back.

Google Workspace Files

Google Docs, Sheets, Slides, and other Workspace files appear in the file list with their native icons. These are cloud-native formats that do not have a traditional file size -- they exist only on Google's servers.

• Downloading: When you download a Google Docs file, AeroFTP exports it to a standard format automatically (Docs to .docx, Sheets to .xlsx, Slides to .pptx).
• Uploading: Standard Office files uploaded to Google Drive remain in their original format. Google does not auto-convert them unless you configure that in Google Drive's own settings.

Shared Drives (Team Drives)

If your Google account has access to Shared Drives (formerly Team Drives), they appear alongside your personal My Drive. Shared Drives have their own storage quota and ownership model -- files belong to the organization, not individual users.

Features

Starring Files

Star and unstar files directly from the right-click context menu. Starred files are marked in Google Drive's metadata and appear in the "Starred" section of the Google Drive web interface.

• Right-click a file and select Star or Unstar.
• The starred status is visible in the file's metadata panel.

Comments

Add comments to any file via the context menu. Comments are visible to all collaborators who have access to the file in Google Drive.

• Right-click a file and select Add Comment.
• A dialog appears where you can type your comment.
• Comments appear in the Google Drive web interface's comment sidebar.

Custom Properties

Set key-value properties and file descriptions through the context menu. Properties are stored in Google Drive's file metadata and can be read by other applications via the API.

• Right-click a file and select Properties.
• Add or edit the file description and custom key-value pairs.

File Versioning

Google Drive retains previous versions of files automatically (for 30 days or 100 versions, whichever comes first). AeroFTP exposes version management through the StorageProvider interface:

• List versions: See all available versions of a file with timestamps and sizes.
• Download a specific version: Retrieve an older version of a file.
• Restore a version: Promote a previous version to become the current version.

Storage Quota

Your Google Drive storage usage is displayed in the status bar at the bottom of the AeroFTP window, showing used space vs. total available space (e.g., 7.2 GB / 15.0 GB).

Note: Google Drive's 15 GB free tier is shared across Gmail, Google Drive, and Google Photos. If your quota appears lower than expected, check your Gmail and Photos usage.

Trash Management

Deleted files are moved to Google Drive's trash (not permanently deleted). You can restore or permanently delete trashed files through AeroFTP.

CLI Usage

The AeroFTP CLI accesses Google Drive through saved connection profiles:

# List root directory
aeroftp ls --profile "Google Drive" /

# List with details (size, date, type)
aeroftp ls --profile "Google Drive" / -l

# Download a file
aeroftp get --profile "Google Drive" /Documents/report.pdf ./

# Upload a file
aeroftp put --profile "Google Drive" /Documents/ ./presentation.pptx

# Search for files
aeroftp find --profile "Google Drive" / -n "*.pdf"

# Show storage quota
aeroftp df --profile "Google Drive"

# Directory tree
aeroftp tree --profile "Google Drive" /Projects/ -d 2

# JSON output for scripting
aeroftp ls --profile "Google Drive" / -l --json

Note: Google Drive CLI access requires a saved profile with valid OAuth tokens. Run the GUI at least once to complete the OAuth flow, then the CLI can reuse the stored tokens.

Common Issues

Tips

• For large uploads, Google Drive uses resumable upload sessions that survive network interruptions. AeroFTP handles this automatically for files larger than 5 MB.
• File names in Google Drive can contain characters that are invalid on local filesystems (e.g. :). AeroFTP sanitizes these transparently during downloads.
• Google Drive API has a rate limit of approximately 12,000 requests per 100 seconds per user. For bulk operations on thousands of files, expect some throttling.
• AeroSync works well with Google Drive using the size + modification time compare mode.

Dropbox

AeroFTP connects to Dropbox via the official Dropbox API v2 with OAuth2 PKCE authentication. Full file management, tags, trash, and versioning support.

Connection Settings

Authentication is handled via OAuth2 PKCE (no client secret required on the device):

1. Click Connect on the Dropbox protocol.
2. A browser window opens to Dropbox's authorization page.
3. Sign in and approve AeroFTP's access.
4. The authorization is completed automatically.

OAuth tokens are stored encrypted in the OS keyring. To use your own app credentials, enter a Client ID in Settings > Cloud Providers.

Features

• Tag Management: Add, remove, and view tags on files and folders via the context menu. Tags use Dropbox's native Tags API, so they sync across all Dropbox clients.
• Trash Management: Deleted files are moved to Dropbox's trash. The Trash Manager dialog lets you browse, restore, and permanently delete trashed items.
• File Versioning: Dropbox retains previous versions of files. Access version history through the context menu.
• File Sharing: Create shared links for files and folders.
• Storage Quota: Used and total storage shown in the status bar.
• Streaming Uploads: Files are uploaded using chunked streaming, preventing out-of-memory issues on large files.

Tips

• Dropbox's free tier (Basic) provides 2 GB of storage.
• Tags are user-scoped -- other collaborators on a shared folder do not see your tags.
• When syncing with AeroSync, Dropbox provides reliable content hashes that enable accurate change detection.
• If you encounter rate limiting (HTTP 429), AeroFTP retries automatically with exponential backoff.

OneDrive

AeroFTP connects to Microsoft OneDrive via the Microsoft Graph API with OAuth2 authentication. Supports personal OneDrive and OneDrive for Business.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the OneDrive protocol.
2. A browser window opens to Microsoft's login page.
3. Sign in with your Microsoft account and approve access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring. To use your own Azure AD app, enter a Client ID and Client Secret in Settings > Cloud Providers.

Features

• Trash Management: Deleted files go to the OneDrive recycle bin. The Trash Manager dialog lets you list, restore, and permanently delete items.
• Resumable Uploads: Files larger than 4 MB are automatically uploaded using Microsoft's resumable upload sessions, which survive network interruptions.
• File Versioning: OneDrive retains version history for files. Browse and restore previous versions.
• Shared Links: Create shareable links with configurable permissions.
• Storage Quota: Used and total storage displayed in the status bar.

Tips

• OneDrive provides 5 GB free with a Microsoft account, or 1 TB with Microsoft 365.
• OneDrive for Business may have different API permissions. If you encounter "Access Denied" errors, your organization's admin may need to approve the app.
• For AeroSync, OneDrive provides file hashes (SHA-1 for personal, QuickXorHash for Business) that enable efficient change detection.
• Large file uploads (>4 MB) use the upload session API automatically -- no configuration needed.

MEGA

AeroFTP connects to MEGA's end-to-end encrypted cloud storage. All files are encrypted client-side with AES-128 before upload. MEGA provides 20 GB of free storage.

Connection Settings

MEGA does not use OAuth. Your password is used locally to derive the AES master key -- it is never sent to MEGA's servers in plaintext.

Features

• End-to-End Encryption: All files are encrypted with AES-128 before leaving your device. MEGA cannot read your files.
• Shared Links: Create encrypted share links. Recipients need the decryption key (included in the link by default).
• Large Storage: 20 GB free tier, one of the most generous free offerings.
• Streaming Transfers: Files are encrypted/decrypted on the fly during upload and download.

Tips

• MEGA's encryption means that server-side operations (rename, move) require re-encrypting metadata. This is handled transparently by AeroFTP.
• If you have 2FA enabled on your MEGA account, you will be prompted for the TOTP code during login.
• MEGA's API has bandwidth quotas on free accounts. If you hit the transfer limit, you will need to wait or upgrade.
• For AeroSync, use the size compare mode since MEGA does not expose file modification times reliably.

Box

AeroFTP connects to Box via the official Box Content API with OAuth2 authentication. Box is a feature-rich cloud storage platform with enterprise capabilities.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the Box protocol.
2. A browser window opens to Box's authorization page.
3. Sign in and grant AeroFTP access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring. To use your own Box app, enter a Client ID and Client Secret in Settings > Cloud Providers.

Features

• Trash Management: Deleted files go to Box's trash. The Trash Manager lets you browse, restore, and permanently delete trashed items.
• Comments: Add comments to files via the context menu. Comments are visible to all collaborators.
• Collaborations: View and manage file/folder collaborations and permissions.
• Tags: Add and manage tags on files. Tag management uses a reusable dialog component shared with Dropbox.
• File Versioning: Box retains previous versions of files for recovery.
• Shared Links: Create shareable links with password protection and expiration options.
• Folder Locks (Enterprise): Lock folders to prevent modifications. Requires a Box Business or Enterprise plan.
• Watermark (Enterprise): Apply watermarks to files for security. Requires Enterprise plan.
• PRO Badge: Enterprise-only features are marked with a PRO badge in the UI.

Tips

• Box provides 10 GB free with a personal account. File upload limit is 250 MB on free plans, 5 GB on Business.
• Box's API rate limits are relatively strict. AeroFTP handles 429 responses with automatic retry.
• For AeroSync, Box provides SHA-1 hashes for files, enabling accurate change detection.
• If you see "terms of service" errors, you may need to accept Box's updated terms in the web interface first.

pCloud

AeroFTP connects to pCloud via their native API with OAuth2 authentication. pCloud offers 10 GB of free storage with US and EU data center options.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the pCloud protocol.
2. A browser window opens to pCloud's authorization page.
3. Sign in and approve access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring.

Data Center Regions

When creating a pCloud account, you choose a data center region:

AeroFTP auto-detects your data center based on the OAuth response. If detection fails, you can set the region manually.

Features

• Trash Management: Deleted files can be recovered from pCloud's trash.
• File Versioning: pCloud retains up to 15 days of version history (30 days on Premium).
• Shared Links: Create download and upload links for files and folders.
• Storage Quota: Used and total storage displayed in the status bar.
• Streaming Transfers: Large files are uploaded and downloaded with streaming I/O.

Tips

• pCloud's 10 GB free tier does not expire, unlike some competitors.
• pCloud also offers lifetime plans (one-time payment) -- a unique offering among cloud providers.
• For AeroSync, pCloud provides file hashes that enable efficient change detection.
• If your account is on the EU server, ensure you selected the EU region during pCloud account creation. You cannot migrate between regions.

Azure Blob Storage

AeroFTP connects to Microsoft Azure Blob Storage using access key authentication. Azure Blob is an enterprise-grade object storage service suitable for large-scale data storage.

Connection Settings

Features

• Container Operations: Browse, upload, download, rename, and delete blobs within a container.
• XML Parsing: Directory listings are parsed using quick-xml (event-based parser) for reliable handling of Azure's XML responses.
• Pagination: NextMarker-based pagination handles containers with large numbers of blobs.
• Blob Versioning: If enabled on the storage account, previous blob versions are accessible.
• SAS Tokens: Generate Shared Access Signature URLs for temporary access to specific blobs.
• Server-Side Encryption: Azure encrypts all blobs at rest by default (SSE with Microsoft-managed keys).

Tips

• Azure Blob Storage is pay-as-you-go with no free tier beyond the initial Azure credits ($200 for 30 days).
• For the best performance, choose a storage account in a region close to your location.
• If you get AuthenticationFailed errors, verify that the access key has not been rotated. Azure allows two keys for zero-downtime rotation.
• Azure Blob does not have a native trash/recycle bin. Deleted blobs are gone unless soft delete is enabled on the storage account.
• For AeroSync, use size + modification time compare mode. Azure provides Content-MD5 headers when set during upload.

4shared

AeroFTP connects to 4shared using their native REST API with OAuth 1.0 (HMAC-SHA1) authentication. 4shared provides 15 GB of free storage.

Connection Settings

Authentication uses OAuth 1.0 with a three-step token flow:

1. Click Connect on the 4shared protocol.
2. A browser window opens to 4shared's authorization page.
3. Approve the access request.
4. The OAuth tokens are exchanged and stored automatically.

Alternatively, you can authenticate with username and password directly using the Full Auth flow.

Features

• OAuth 1.0 Signing: All API requests are signed with HMAC-SHA1 per RFC 5849. The signing module (oauth1.rs) is reusable across providers.
• ID-Based File System: 4shared uses numeric IDs for files and folders rather than paths. AeroFTP maintains a folder/file cache for path resolution.
• Shared Links: Files uploaded to 4shared are shareable by default with public download links.
• Per-Entry Parsing: Directory listings use fault-tolerant JSON parsing -- a malformed entry is skipped rather than failing the entire listing.

Tips

• 4shared's free tier provides 15 GB but has bandwidth limits on downloads.
• The API returns file and folder IDs as either strings or integers depending on the endpoint. AeroFTP handles this with a custom string_or_i64 deserializer.
• 4shared does not provide a trash/recycle bin through the API. Deletions are permanent.
• Relative paths in file operations are resolved against the current directory automatically.

Filen

AeroFTP connects to Filen's end-to-end encrypted cloud storage. All file contents and metadata are encrypted client-side with AES-256 before upload. Filen provides 10 GB of free storage.

Connection Settings

2FA Support

If your Filen account has two-factor authentication enabled, AeroFTP shows a conditional 2FA code field. The TOTP code is sent with the login request. If 2FA is not enabled, AeroFTP sends the default placeholder value XXXXXX as required by Filen's API.

Features

• End-to-End Encryption: File contents are encrypted with AES-256 on your device. File metadata (names, paths) is also encrypted. Filen has zero knowledge of your data.
• Client-Side Key Derivation: Your password is used locally to derive encryption keys. It is never sent to Filen's servers.
• Streaming Encryption: Files are encrypted and decrypted on the fly during transfers.

Tips

• Filen's 10 GB free tier includes E2E encryption -- most competitors charge for client-side encryption.
• Filen does not expose a trash or versioning API. Deleted files cannot be recovered through AeroFTP.
• Because all file metadata is encrypted, directory listings require decrypting each entry's metadata. This can be slower than non-encrypted providers for large directories.
• For AeroSync with Filen, use the size compare mode since encrypted timestamps may differ from local file times.

Zoho WorkDrive

AeroFTP connects to Zoho WorkDrive via the official API with OAuth2 authentication. Zoho WorkDrive is a team-oriented cloud storage service with label management, file versioning, and 8 regional data centers.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the Zoho WorkDrive protocol.
2. A browser window opens to Zoho's consent screen.
3. Sign in and grant access.
4. AeroFTP detects your team ID automatically.

To use your own OAuth credentials, enter a Client ID and Client Secret in Settings > Cloud Providers.

Regional Endpoints

Zoho operates in 8 regions. The OAuth flow auto-detects your region:

Features

• Team Labels: Manage team-level color-coded labels. Apply and remove labels on files via a dedicated dialog. Labels are shared across team members.
• File Versioning: View the version history of files, download specific versions, and restore (promote) a previous version to current.
• Trash Management: Deleted files go to the WorkDrive trash. The Trash Manager lets you restore or permanently delete items.
• Share Links: Create shareable links with configurable access levels.
• Storage Quota: Team storage usage displayed in the status bar.

Tips

• Zoho WorkDrive's free tier provides 5 GB per team. Paid plans start at 5 TB.
• Labels are team-scoped, meaning all team members see and share the same label set.
• If you need to switch regions, you must create a new Zoho account in the target region -- migration is not supported.
• For AeroSync, Zoho provides modification timestamps that enable reliable change detection with the overwrite if newer strategy.

Internxt Drive

AeroFTP connects to Internxt Drive, an end-to-end encrypted cloud storage service with a zero-knowledge architecture. Internxt provides 10 GB of free storage.

Connection Settings

Authentication is handled via OAuth2 PKCE:

1. Click Connect on the Internxt protocol.
2. A browser window opens to Internxt's authorization page.
3. Sign in and approve access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring.

Features

• End-to-End Encryption: All files are encrypted client-side before upload. Internxt uses AES-256 with a zero-knowledge design -- the service cannot access your data.
• OAuth2 PKCE: Secure authorization flow without exposing a client secret. No manual API key management required.
• Full File Operations: Upload, download, rename, move, and delete files and folders.
• Privacy-First: Internxt is headquartered in the EU (Spain) and complies with GDPR. No tracking, no data mining.

Tips

• Internxt's 10 GB free tier includes full E2E encryption at no additional cost.
• Because all metadata is encrypted, some operations (directory listing, rename) involve additional decryption steps compared to non-encrypted providers.
• Internxt does not currently expose a trash or file versioning API. Deletions through AeroFTP are permanent.
• For AeroSync, use the size compare mode. Encrypted modification times may not match local timestamps.
• Internxt is a good choice if privacy and EU data residency are priorities.

kDrive

AeroFTP connects to Infomaniak kDrive via the official API with OAuth2 authentication. kDrive is a Swiss cloud storage service by Infomaniak, offering 15 GB of free storage.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the kDrive protocol.
2. A browser window opens to Infomaniak's authorization page.
3. Sign in and approve access.
4. AeroFTP retrieves your available drives and selects the primary drive.

OAuth tokens are stored encrypted in the OS keyring. To use your own OAuth credentials, enter a Client ID and Client Secret in Settings > Cloud Providers.

Features

• Drive Selection: If your account has multiple kDrives, AeroFTP uses the primary drive by default.
• Cursor-Based Pagination: Large directories are loaded efficiently using cursor pagination.
• Trash Management: Deleted files go to the kDrive trash and can be restored.
• File Versioning: kDrive retains previous versions of files. View and restore versions through AeroFTP.
• Share Links: Create shareable links for files and folders.
• Storage Quota: Used and total storage displayed in the status bar.

Tips

• kDrive provides 15 GB free, which is generous among European cloud providers.
• Infomaniak is based in Switzerland, offering strong privacy protections under Swiss law.
• kDrive integrates with Infomaniak's broader ecosystem (email, web hosting, Swiss Transfer).
• For AeroSync, kDrive provides reliable modification timestamps for change detection.

Koofr

AeroFTP connects to Koofr via the official API with OAuth2 PKCE authentication. Koofr is an EU-based cloud storage service (Slovenia) providing 10 GB of free storage.

Connection Settings

Authentication is handled via OAuth2 PKCE:

1. Click Connect on the Koofr protocol.
2. A browser window opens to Koofr's authorization page.
3. Sign in and approve access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring.

Features

• Trash Management: Deleted files go to Koofr's trash. The Trash Manager lets you browse, restore, and empty the trash.
• Share Links: Create shareable download links for files and folders.
• Storage Quota: Used and total storage displayed in the status bar.
• Multi-Provider Hub: Koofr can aggregate storage from Google Drive, Dropbox, OneDrive, and Amazon S3 into a single view (configured on Koofr's web interface).

Tips

• Koofr's 10 GB free tier is lifetime -- no expiration, no forced upgrades.
• Koofr is based in Slovenia (EU) and complies with GDPR.
• Koofr supports connecting external cloud accounts (Google Drive, Dropbox, OneDrive) as sub-mounts -- this is configured on Koofr's website, not through AeroFTP.
• For AeroSync, Koofr provides reliable modification timestamps for change detection.
• Koofr offers a unique "Vault" feature on their end (client-side encryption of a subfolder). This is separate from AeroFTP's AeroVault.

FileLu

AeroFTP connects to FileLu via their native REST API with API key authentication. FileLu provides 10 GB of free storage with unique file-level security features.

Connection Settings

FileLu also supports FTP, FTPS, WebDAV, and S3 access. These can be configured as separate connections using the respective protocol presets.

Features

• File Passwords: Set a password on individual files to restrict access. Recipients must enter the password to download.
• File Privacy: Toggle files between public and private visibility.
• File Cloning: Duplicate files server-side without re-uploading.
• Folder Passwords: Protect entire folders with a password.
• Folder Settings: Configure per-folder options (description, password, privacy).
• Trash Management: List deleted files, restore individual files/folders, or permanently delete items via the Trash Manager.
• Remote URL Upload: Upload files to FileLu by providing a URL. FileLu downloads the file server-side.
• Share Links: Files have shareable download links.

Tips

• FileLu's free tier provides 10 GB. Premium plans offer up to 500 TB.
• The API key is the only credential needed -- no OAuth flow, no email/password.
• FileLu's alternative access methods (FTP, FTPS, WebDAV, S3) can be configured as separate connections in AeroFTP if you prefer a standard protocol.
• For AeroSync, FileLu provides file size metadata for the size compare mode. The remote URL upload feature can be useful for server-to-server transfers.

Yandex Disk

AeroFTP connects to Yandex Disk via the official REST API with OAuth2 authentication. Yandex Disk provides 5 GB of free storage.

Connection Settings

Authentication is handled via OAuth2:

1. Click Connect on the Yandex Disk protocol.
2. A browser window opens to Yandex's authorization page.
3. Sign in and approve access.
4. Authorization completes automatically.

OAuth tokens are stored encrypted in the OS keyring. To use your own OAuth credentials, enter a Client ID and Client Secret in Settings > Cloud Providers.

Features

• Trash Management: Full trash lifecycle -- list, restore, permanently delete individual items, and empty the entire trash. Accessible via the Trash Manager dialog.
• Share Links: Create public download links for files and folders.
• Storage Quota: Used and total storage displayed in the status bar.
• Full File Operations: Upload, download, rename, move, copy, and delete.

Tips

• Yandex Disk provides 5 GB free. Additional storage can be earned through Yandex promotions or purchased.
• Yandex also offers Yandex Object Storage (S3-compatible). This is a separate service configured using the S3 preset (storage.yandexcloud.net).
• For AeroSync, Yandex Disk provides modification timestamps and MD5 hashes for reliable change detection.
• If you are outside Russia/CIS, connection speeds to Yandex servers may be slower due to geographic distance.

OpenDrive

AeroFTP connects to OpenDrive via their native REST API with session-based authentication. OpenDrive provides 5 GB of free storage.

Connection Settings

Authentication creates a session token that is maintained for the duration of the connection.

Features

• Trash Management: Deleted files go to OpenDrive's trash. The Trash Manager lets you browse, restore, and permanently delete trashed items. Accessible from the context menu.
• MD5 Checksums: OpenDrive provides MD5 hashes for files, enabling integrity verification after transfers.
• Expiring Share Links: Create download links with configurable expiration dates.
• Zlib Compression: Some API responses use zlib compression for reduced bandwidth.
• Full File Operations: Upload, download, rename, move, and delete files and folders.

Tips

• OpenDrive's free tier provides 5 GB with a 100 MB per-file size limit. Paid plans remove the file size restriction.
• OpenDrive sessions expire after inactivity. AeroFTP handles re-authentication transparently if the session times out.
• For AeroSync, OpenDrive's MD5 checksums enable the checksum compare mode for the most accurate change detection.
• OpenDrive share links can be set to expire after a specific date -- useful for temporary file sharing.

Jottacloud

AeroFTP connects to Jottacloud via WebDAV. Jottacloud is a Norwegian cloud storage service that provides 5 GB of free storage with data residency in Norway.

Connection Settings

Jottacloud is accessed through the WebDAV protocol. When you select the Jottacloud preset, AeroFTP configures the endpoint automatically.

Features

• WebDAV Access: Standard WebDAV file operations -- upload, download, rename, move, and delete.
• Norwegian Data Residency: All data is stored in Norway, subject to Norwegian privacy laws.
• Unlimited Storage (paid): Jottacloud's paid plans offer unlimited storage, making it attractive for large backups.

Tips

• Jottacloud's free tier provides 5 GB. The Personal plan offers unlimited storage for a monthly fee.
• If you have 2FA enabled on your Jottacloud account, you may need to create an app-specific password in your account settings for WebDAV access.
• Since Jottacloud uses WebDAV, it inherits the same characteristics as other WebDAV connections -- no trash API, no versioning API through this interface.
• For AeroSync, use size + modification time compare mode. WebDAV access provides reliable file metadata.
• Jottacloud is a good choice for users who prioritize Nordic data residency and privacy.

GitHub

AeroFTP treats GitHub repositories as remote filesystems. Every write operation -- upload, delete, rename, move -- creates a real Git commit on the target branch. This means you can manage repository contents, upload release assets, and browse code using the same file manager interface as any other protocol. GitHub is the 23rd protocol supported by AeroFTP.

Capabilities

Authentication

AeroFTP supports three authentication methods for GitHub, each suited to different use cases.

1. Authorize with GitHub (Recommended)

One-click browser authentication via the AeroFTP GitHub App at github.com/apps/aeroftp. This is the easiest method -- no tokens to manage, no expiration dates to track.

• Click Authorize with GitHub in the connection dialog.
• Your browser opens to GitHub's authorization page.
• Grant the AeroFTP GitHub App access to your repositories.
• The authorization code is captured automatically.

Commits are attributed to your GitHub username and avatar. The app requests only the minimum permissions needed: repository contents (read/write) and metadata (read).

2. Personal Access Token

For users who prefer manual token management or need access to organizations that have not installed the AeroFTP GitHub App.

Generate a fine-grained Personal Access Token from github.com/settings/personal-access-tokens/new.

Required permissions:

Paste the token into the connection dialog. Commits are attributed to the token owner's GitHub identity (username and avatar).

Tip: Fine-grained tokens can be scoped to specific repositories, which is more secure than classic tokens that grant access to all repositories.

3. GitHub App with .pem Key

Create a custom GitHub App for branded bot commits. This is the best option for teams and CI workflows where you want commits to appear as a bot rather than a personal account.

• Create a GitHub App in your organization's settings.
• Generate a private key (.pem file) for the app.
• Enter the App ID and upload the .pem file in AeroFTP's connection dialog.

The commit author appears as yourapp[bot] with your custom app logo. This provides clear audit trails in repositories where automated and manual changes should be distinguishable.

Write Modes

AeroFTP automatically detects the branch protection level and selects the appropriate write mode. The current write mode is displayed in the status bar.

Write mode detection happens automatically on connection. If you switch branches, the write mode is re-evaluated for the new branch.

Branch Awareness

AeroFTP lists all branches in the repository and lets you switch between them using a dropdown in the toolbar. The current branch name is always visible.

• Default branch: On connection, AeroFTP selects the repository's default branch (usually main or master).
• Branch switching: Select any branch from the dropdown to browse its contents. The file list updates immediately.
• Branch in URL mode: When using the CLI, append @branch to the repository path to select a branch.

Batch Commits

When uploading multiple files in a single operation, AeroFTP prompts for a commit message once and reuses it across all file uploads. This keeps the commit history clean and avoids per-file commit noise.

• A dialog appears showing the files that will be committed.
• Enter a descriptive commit message.
• All files are committed with the same message.
• Each file upload creates a separate commit (GitHub's Contents API limitation), but the consistent message groups them logically.

Release Asset Management

GitHub Releases are exposed through a virtual /.github-releases/ directory at the repository root. Each release tag appears as a subdirectory containing its assets.

/.github-releases/
  v2.9.8/
    aeroftp_2.9.8_amd64.deb
    aeroftp_2.9.8_x86_64.rpm
    aeroftp_2.9.8.AppImage
  v2.9.7/
    aeroftp_2.9.7_amd64.deb
    ...

• Upload assets up to 2 GiB per file by dragging files into a release directory.
• Download release assets with double-click or the CLI get command.
• Delete assets via the right-click context menu.
• Assets are managed via the GitHub Releases API, not Git LFS.

CLI Usage

GitHub repositories are fully accessible from the AeroFTP CLI using saved profiles or URL mode.

Profile Mode

# List repository root
aeroftp ls --profile "My GitHub Repo" / -l

# Browse a subdirectory
aeroftp ls --profile "My GitHub Repo" /src/components/ -l

# Upload a file (creates a commit)
aeroftp put --profile "My GitHub Repo" /src/ ./fix.py

# Download a file
aeroftp get --profile "My GitHub Repo" /README.md ./

# Delete a file (creates a commit)
aeroftp rm --profile "My GitHub Repo" /old-file.txt

# Directory tree
aeroftp tree --profile "My GitHub Repo" /src/ -d 3

# Search for files
aeroftp find --profile "My GitHub Repo" / -n "*.tsx"

URL Mode

# Browse with a Personal Access Token
aeroftp ls github://token:YOUR_PAT@owner/repo /src/

# Browse a specific branch
aeroftp ls github://token:YOUR_PAT@owner/repo@develop /

# Download from a feature branch
aeroftp get github://token:YOUR_PAT@owner/repo@feature/new-ui /src/App.tsx ./

The @branch suffix selects a specific branch. Without it, the repository's default branch is used.

Technical Details

Limitations

• API rate limits apply -- heavy operations on large repositories may require pacing. AeroFTP does not currently implement rate limit backoff for GitHub.
• Files larger than 100 MiB must be uploaded as release assets, not repository files. This is a GitHub limitation, not an AeroFTP limitation.
• Binary files are stored as-is in Git (no LFS integration). Large binary files will bloat the repository.
• Branch protection rules are respected -- AeroFTP cannot bypass required reviews, status checks, or signed commit requirements.
• Each file upload is a separate commit -- the GitHub Contents API does not support atomic multi-file commits. Use the Git protocol directly for atomic operations.

AeroSync

AeroSync is AeroFTP's professional file synchronization engine. It supports bidirectional sync across all 22 protocols with conflict resolution, scheduling, bandwidth throttling, transfer journaling, and checkpoint-based resume. AeroSync operates through a two-tab interface: Quick Sync for common scenarios and Advanced for granular control over every aspect of the sync process.

Quick Sync Tab

The Quick Sync tab presents three preset cards that cover the most common synchronization scenarios. Select a card and click Start to begin immediately with sensible defaults.

Mirror

Produces an exact copy of your local directory on the remote server. Files that exist on the remote but not locally are deleted (orphan removal). This is ideal for deploying websites, publishing build artifacts, or maintaining a canonical remote copy.

• Direction: Local to Remote
• Orphan deletion: Enabled
• Verification: Size only
• Use case: Web deployment, content publishing

Two-Way

Synchronizes changes in both directions. Files modified locally are uploaded; files modified remotely are downloaded. Neither side deletes files from the other. When both copies have changed, the Conflict Resolution Center activates.

• Direction: Bidirectional
• Orphan deletion: Disabled
• Verification: Size + modification time
• Use case: Collaborative workflows, shared project folders

Backup

Copies local files to the remote server without removing anything on the remote side. Uses SHA-256 checksum verification to guarantee data integrity after transfer. This is the safest preset for archival purposes.

• Direction: Local to Remote
• Orphan deletion: Disabled
• Verification: Full checksum (SHA-256)
• Use case: Offsite backup, archival storage

Advanced Tab

The Advanced tab provides full control over synchronization behavior through four collapsible accordion sections. Each section expands with a smooth CSS transition to reveal its settings.

Direction Section

Choose the sync direction and configure orphan handling:

• Local to Remote — push local changes to the server
• Remote to Local — pull remote changes to your machine
• Bidirectional — sync changes in both directions
• Delete orphans toggle — remove files on the destination that do not exist on the source

Compare Section

Define how AeroSync determines whether a file needs to be transferred:

• overwrite_if_newer — transfer only when the source file has a more recent modification time
• overwrite_if_different — transfer when file size or checksum differs, regardless of timestamp
• skip_if_identical — skip files where both size and SHA-256 hash match exactly
• Compare checksum toggle — enable SHA-256 hashing during the scan phase (streaming 64 KB chunks)

Transfer Section

Control retry behavior, verification policies, and per-file timeouts:

• Retry count — number of retry attempts per file (default: 3)
• Retry delay — base delay with exponential backoff (default: 500 ms, 2x multiplier, 10-second cap)
• Per-file timeout — maximum time allowed for a single file transfer (default: 2 minutes)
• Post-transfer verification — 4 policies: None, Size Only, Size + Mtime, Full (SHA-256 re-hash after transfer)

Automation Section

Configure scheduling, filesystem watching, and bandwidth limits within this section (see dedicated sections below for details).

Sync Profiles

AeroSync ships with 5 built-in profiles. You can also create, save, and load custom profiles that bundle all settings into a single configuration.

Custom profiles are saved to the vault database and can be selected from the dropdown in the SyncPanel header.

Speed Modes

AeroSync offers five speed presets that automatically configure parallel streams, compression, and delta sync. Select a speed mode from the dropdown to apply its settings instantly.

Warning: Maniac mode is a Cyber theme easter egg. It disables all safety checks for maximum throughput, including retry limits (max_retries=0). Post-sync verification runs automatically to compensate. A mandatory verification pass executes after every Maniac sync to catch any transfer errors.

Conflict Resolution Center

When both the local and remote copies of a file have been modified since the last sync, AeroSync pauses and presents the Conflict Resolution Center. This interface lists every conflicting file with metadata from both sides (size, modification time, checksum) so you can make informed decisions.

Per-File Resolution

For each conflicting file, three options are available:

• Keep Local — upload the local version, overwriting the remote copy
• Keep Remote — download the remote version, overwriting the local copy
• Skip — leave both versions untouched for this sync run

Batch Actions

When dealing with many conflicts, batch actions resolve all files at once:

• Keep Newer All — for each file, keep whichever version has the more recent modification time
• Keep Local All — upload all local versions
• Keep Remote All — download all remote versions
• Skip All — leave all conflicting files untouched

All conflict decisions are recorded in the transfer journal for auditing and reproducibility.

Scheduler

Configure AeroSync to run automatically on a recurring basis. The scheduler UI provides intuitive controls for timing and scope.

• Interval selector — choose a sync frequency from every 5 minutes up to every 24 hours
• Time window — restrict sync operations to specific hours (e.g., 02:00 to 06:00) to avoid interfering with active work or peak bandwidth periods
• Day picker — select which days of the week the scheduler should be active (weekdays only, weekends only, or custom)
• Pause / Resume — temporarily suspend the scheduler with a single click; a live countdown displays the time until the next scheduled sync
• Overnight carry-over — if a time window spans midnight (e.g., 23:00 to 03:00), AeroSync handles the day boundary correctly

Filesystem Watcher

AeroSync can monitor local directories for real-time changes using inotify on Linux. A health indicator in the sync panel shows the watcher status:

• Active (green) — watcher is running and monitoring all configured paths
• Warning (yellow) — inotify watch count is approaching the system limit (/proc/sys/fs/inotify/max_user_watches)
• Inactive (gray) — watcher is not running

When the watcher detects file changes, it can trigger an immediate sync or queue changes for the next scheduled run, depending on your configuration.

Transfer Journal

Every sync operation is logged to a persistent JSON journal stored in ~/.config/aeroftp/sync-journal/. Journals are keyed by a hash of the local and remote path pair, ensuring each sync relationship maintains its own history.

Checkpoint and Resume

If a sync operation is interrupted (application crash, network failure, manual cancellation), AeroSync detects the incomplete journal on the next run and displays a resume banner offering to continue from the last successfully transferred file.

SHA-256 Verification

When the Compare checksum option is enabled, AeroSync computes SHA-256 hashes during the scan phase using streaming 64 KB chunk reads. This avoids loading entire files into memory and enables accurate change detection even when file timestamps are unreliable.

Journal Maintenance

• Auto-cleanup — journals older than 30 days are automatically deleted when the sync panel opens
• Clear History — a button with confirmation dialog to delete all journals at once
• Journals use compact JSON serialization (no pretty-printing) to minimize disk usage

Bandwidth Control

Limit upload and download speeds independently to prevent AeroSync from saturating your network connection. Available speed limits range from 128 KB/s to 10 MB/s, plus an "Unlimited" option.

The bandwidth limiter auto-detects whether the active backend is FTP (where throttling is applied at the socket level) or a cloud provider API (where throttling is applied at the HTTP request level). Current limits are loaded from the server connection when the sync panel opens.

Multi-Path Sync Pairs

Define multiple local-to-remote path mappings within a single sync configuration. Each pair syncs independently, allowing you to synchronize different directories to different remote locations in one operation. The Multi-Path Editor provides CRUD controls for adding, editing, and removing path pairs.

Dry-Run Export

Before executing a sync, run a dry-run to preview exactly what will happen. The dry-run scans both sides, computes the diff, and exports the planned operations as either:

• JSON — structured format for programmatic analysis or scripting
• CSV — tabular format for review in spreadsheet applications

The dry-run report includes file paths, planned actions (upload, download, delete, skip), file sizes, and the reason for each decision.

Safety Score

A visual badge in the sync panel header displays a Safety Score based on your current configuration. Configurations that delete orphans, disable verification, or use high parallelism receive lower scores, helping you understand the risk level before starting a sync.

Template Export and Import

Save your entire sync configuration (profile, speed mode, paths, scheduler settings, bandwidth limits) as an .aerosync file. These portable template files can be:

• Shared with team members for consistent sync setups
• Backed up alongside your project
• Imported on a different machine to replicate the same sync configuration

Templates are exported and imported via Tauri's native file dialog.

Rollback Snapshots

Create pre-sync snapshots of your data that can be restored if a sync produces unwanted results.

• Create snapshot — save the current state before running a sync
• List snapshots — view all available snapshots with timestamps and file counts
• Preview — inspect the files contained in a snapshot before restoring
• Delete — remove old snapshots to free disk space

Error Handling

AeroSync classifies errors into 10 categories using a structured taxonomy. Each error carries a retryability hint that determines whether AeroSync will automatically retry the operation.

The sync report groups errors by category with dedicated icons, showing retryable vs. non-retryable counts. This makes it straightforward to identify systemic issues (e.g., all failures are permission errors on a specific directory) versus transient problems (e.g., intermittent network timeouts).

Exponential Backoff Retry

Failed transfers are retried automatically with configurable exponential backoff:

• Base delay: 500 ms (configurable)
• Multiplier: 2x per retry
• Maximum delay cap: 10 seconds
• Default retries: 3 per file
• Per-file timeout: 2 minutes

Delay values are guarded against NaN and Infinity to prevent runaway retry loops.

AeroVault

AeroVault is AeroFTP's encrypted container system. It creates portable .aerovault files that can store any number of files and directories under strong authenticated encryption. AeroVault v2 provides military-grade cryptography with seven distinct layers, surpassing Cryptomator in key derivation strength, nonce-misuse resistance, and optional cascade encryption.

Home Screen

When you open AeroVault from the titlebar icon or the View menu, the home screen presents three options: create a new vault, open an existing vault, or reopen a recent vault.

Recent Vaults

AeroVault tracks recently opened vaults in a SQLite WAL-backed database. Each entry displays:

• The vault filename and full path
• Security badges showing the encryption algorithms used
• The last-opened timestamp
• A one-click button to reopen the vault directly

Recent vaults are sorted by last access time, making it easy to return to frequently used containers.

Creating a Vault

Click Create New Vault to begin the vault creation workflow.

1. Choose a save location — select where the .aerovault file will be stored using the native file dialog.
2. Set a master password — this password is the sole key to your vault. AeroVault derives the encryption key using Argon2id with parameters that exceed OWASP 2024 recommendations (128 MiB memory, 4 iterations, 4 parallel lanes).
3. Enable cascade mode (optional) — adds a second encryption layer using ChaCha20-Poly1305 on top of AES-256-GCM-SIV. This provides defense-in-depth: even if one algorithm is compromised, the other still protects your data.
4. Enable TOTP 2FA (optional) — require a 6-digit time-based one-time password in addition to the master password every time the vault is opened. See TOTP 2FA for setup instructions.

After creation, the vault opens immediately and you can begin adding files.

Opening a Vault

Click Open Vault or select a recent vault to enter the password prompt.

The open screen displays security badges confirming the cryptographic algorithms protecting the vault:

• AES-256-GCM-SIV — content encryption (nonce-misuse resistant, RFC 8452)
• Argon2id — key derivation (128 MiB / t=4 / p=4)
• AES-256-KW — key wrapping (RFC 3394)
• HMAC-SHA512 — header integrity verification

If TOTP 2FA is enabled, a second field appears for the 6-digit code. Rate limiting with exponential backoff protects against brute-force attempts (5 attempts before lockout, escalating from 30 seconds to 15 minutes).

Browsing a Vault

Once unlocked, the vault browser presents the contents in a familiar file-list interface.

Available Operations

• Add files — drag files into the vault browser or click the Add button to select files via the native dialog. Files are encrypted and added immediately.
• Add files to subdirectory — navigate to a folder within the vault and add files directly into it.
• Create directories — organize vault contents into a hierarchical folder structure with breadcrumb navigation. Intermediate directories are created automatically.
• Extract individual files — select one or more files and extract them to a local directory. Decryption happens on-the-fly.
• Extract all — decrypt and extract the entire vault contents at once.
• Delete entries — remove files or entire directory trees from the vault (recursive deletion supported).
• Change password — re-encrypt the vault with a new master password without extracting and re-adding files.

Vault Inspection

The vault_peek command (also available as an AeroAgent tool) inspects a vault header without requiring the password, revealing the vault version, encryption parameters, and file count.

Remote Vault Support

AeroVault can open .aerovault files stored on remote servers across any of AeroFTP's 22 supported protocols.

The workflow is:

1. Right-click a .aerovault file on a remote server and select Open AeroVault.
2. AeroFTP downloads the vault to a temporary local location.
3. Enter the master password to unlock and browse the vault contents.
4. Make changes (add, extract, delete files) as needed.
5. Click Save & Close to re-encrypt and upload the modified vault back to the remote server.

Security validations run before any operation: null byte rejection, path traversal prevention, symlink resolution, and canonicalize() verification. On Unix systems, the temporary file is created with 0o600 permissions (owner read/write only).

Folder Encryption

Right-click any local directory and select Encrypt as AeroVault to create a vault containing the entire directory tree.

AeroFTP performs a recursive walkdir scan of the directory, showing a progress indicator as it encrypts each file. The resulting .aerovault file is saved alongside the original directory (or at a location you choose). This is useful for encrypting project folders, document archives, or any directory structure you want to protect.

Cryptomator Compatibility

AeroVault provides read-only support for Cryptomator vault format 8 containers as legacy compatibility. Access Cryptomator vaults through the right-click context menu rather than the main AeroVault interface.

Cryptomator vaults use a different cryptographic stack:

• scrypt for key derivation
• AES-256-KW for key wrapping
• AES-256-SIV for filename encryption
• AES-256-GCM for content encryption

Recommendation: AeroVault v2 is recommended for new vaults. It provides stronger key derivation (Argon2id vs. scrypt), nonce-misuse resistance (GCM-SIV vs. GCM), optional cascade encryption, and TOTP 2FA support.

Encryption Architecture

AeroVault v2 uses a seven-layer cryptographic design. Each layer addresses a specific threat:

Argon2id Parameters

The Argon2id configuration uses 128 MiB of memory, 4 time iterations, and 4 parallel lanes. This exceeds the OWASP 2024 minimum recommendation of 19 MiB / t=2, providing significantly stronger resistance against GPU-based and ASIC-based brute-force attacks.

Comparison with Cryptomator

File Format

The .aerovault binary format consists of three sections:

[512-byte header] [AES-SIV encrypted manifest] [AES-256-GCM-SIV chunked data...]

• Header (512 bytes) — contains the vault version, Argon2id salt, wrapped key material, and HMAC-SHA512 integrity tag
• Manifest — an AES-256-SIV encrypted index of all files and directories with their encrypted filenames, sizes, and offsets
• Data — file contents encrypted in 64 KB chunks using AES-256-GCM-SIV (and optionally ChaCha20-Poly1305 in cascade mode)

AeroVault files are registered as a MIME type on all platforms with dedicated icons in 8 PNG sizes (16 px to 512 px), SVG, ICO, and ICNS. Double-clicking a .aerovault file opens it directly in AeroFTP via the deep-link handler, with single-instance argv forwarding for already-running instances.

AeroAgent

AeroAgent is AeroFTP's AI-powered assistant for natural language file management, code editing, and server operations. It integrates with 19 AI providers, exposes 47 built-in tools, and operates across all 22 file transfer protocols through a unified backend.

Welcome Screen

When you first open AeroAgent (via the AeroTools panel or Ctrl+Shift+A), the welcome screen presents a 3x3 capability grid showing what AeroAgent can do.

The nine capabilities displayed are:

Below the grid, quick prompts provide one-click starting points. These are context-aware: when connected to a server, prompts reference remote operations; in AeroFile (local-only) mode, prompts focus on local file management.

If no AI provider API key is configured, a setup banner guides you to Settings > AI > Providers.

Chat Interface

The main chat interface provides a streaming markdown conversation with the AI, including tool execution results, code blocks with action buttons, and thinking visualization.

Streaming Markdown

Messages render incrementally as the AI generates them. The renderer uses a dual-segment architecture:

• FinalizedSegment (React.memo) — completed paragraphs, code blocks, and lists that never re-render
• StreamingSegment — the currently generating text that updates in real-time

This approach provides smooth streaming without the performance penalty of re-rendering the entire message on every token.

Code Block Actions

Every code block in a response includes action buttons:

• Copy — copy the code to the clipboard
• Apply — write the code to a file (prompts for path if not obvious from context)
• Diff — show a side-by-side diff against the current file contents
• Run — execute the code block as a shell command (with approval)

Thinking Visualization

When using providers that support reasoning (Anthropic extended thinking, OpenAI o3 reasoning, DeepSeek-R1), a collapsible ThinkingBlock displays the model's internal reasoning with token count and duration metrics.

Tool Approval

When AeroAgent calls a tool rated as medium or high danger, an approval dialog appears showing the tool name, parameters, and danger level.

For batch tool calls, a BatchToolApproval dialog presents all pending tools at once, allowing you to approve or reject each individually or approve all.

AI Settings

Configure providers, models, and behavior in the AI Settings panel, accessible from Settings > AI or the gear icon in the AeroAgent header.

The settings panel includes seven tabs:

1. Provider — select and configure AI providers, browse the Provider Marketplace
2. Model — choose the model, set temperature, max tokens, and thinking budget
3. Tools — enable/disable individual tools, set default approval behavior
4. System Prompt — edit the base system prompt with a toggle and textarea
5. Macros — create and manage tool chain macros with {{variable}} templates
6. Plugins — browse, install, and manage plugins from the GitHub-based registry
7. History — configure retention policies, search chat history, view usage stats

Supported AI Providers

Configure providers in Settings > AI > Providers, or browse the Provider Marketplace to discover and add new ones. The marketplace presents providers in a searchable grid organized by category with feature badges and pricing tiers.

Ollama Integration

For local AI models, AeroAgent includes Ollama-specific features:

• Model auto-detection via GET /api/tags with a "Detect" button in AI Settings
• Pull model from UI with NDJSON streaming progress bar
• GPU monitoring via ollama_list_running showing VRAM usage
• 8 model family profiles with detectOllamaModelFamily() for optimized prompting

Tool Reference (47 Tools)

Remote Operations (9 tools)

Local File Operations (16 tools)

Content Inspection (7 tools)

Batch Transfer, Archives, Context and Crypto

Application Control, Clipboard and Memory

Server Management (2 tools)

server_exec is a uniquely powerful tool. AeroAgent can autonomously connect to any saved server and perform 10 operations (ls, cat, get, put, mkdir, rm, mv, stat, find, df) without credentials ever being exposed to the AI model. Passwords are resolved from the encrypted vault entirely in Rust. The AI sees only server names and results.

Shell Execution (1 tool)

Safety System

Three Danger Levels

Path Validation

All file operations validate against null bytes, .. traversal, symlink resolution, 4096-character path limit, and a system path denylist (/proc, /sys, /dev, /boot, /root, /etc/shadow, ~/.ssh, ~/.gnupg, ~/.aws, /run/secrets).

Shell Command Denylist

shell_execute blocks dangerous patterns: rm -rf /, mkfs, dd of=/dev/, shutdown, reboot, fork bombs, chmod 777 /, sudo, eval, curl | sh, and 20+ additional patterns. Shell meta-characters (|, ;, `, $, &) are also blocked.

Execution Pipeline

DAG-Based Parallel Execution

When the AI requests multiple tool calls, AeroAgent builds a Directed Acyclic Graph based on path dependencies. Read-only tools on different paths execute in parallel; mutating tools on shared paths are serialized via topological sort (Kahn's algorithm).

Multi-Step Autonomous Execution

AeroAgent supports multi-step workflows: up to 10 steps by default, 50 in Extreme Mode. After each step, the AI decides whether to respond or call more tools. A circuit breaker halts execution on consecutive errors.

Duplicate Call Prevention

An executedToolSignaturesRef deduplication mechanism prevents models (particularly Llama and other open-source models) from repeating identical tool calls within a multi-step execution run.

Error Recovery

8 strategies with automatic analysis: not-found suggests rag_search, permission-denied suggests listing parent, rate limits (429/503) retry with exponential backoff, timeouts suggest smaller scope, connection loss prompts reconnection, and large files suggest chunked approaches.

Context Intelligence

AeroAgent auto-detects project type from 10 marker files (Cargo.toml, package.json, pom.xml, requirements.txt, go.mod, Gemfile, composer.json, *.csproj, CMakeLists.txt, build.gradle) and injects relevant context. The system prompt is dynamically composed from:

1. Base personality — AeroAgent identity, tone, protocol expertise
2. Provider profile — per-provider optimization (e.g., Anthropic cache hints, OpenAI structured outputs)
3. Connection context — AeroCloud vs Server vs AeroFile mode, current host/port/user
4. Tool definitions — all 47 tools with schemas
5. Project context — detected language, framework, file dependency graph
6. RAG results — indexed file previews and search hits
7. Agent memory — persistent notes from previous sessions (.aeroagent file)

A sliding-window token budget (70% of provider max) with automatic summarization manages context size. The TokenBudgetIndicator component shows real-time token usage with three budget modes.

Plugin System

Extend AeroAgent with custom tools via JSON manifests and shell scripts. Plugins are discovered from a GitHub-based registry, verified with SHA-256 integrity at install and before each execution, and support event-driven hooks (file:created, transfer:complete, sync:complete). Manage plugins in AI Settings > Plugins.

The Plugin Browser UI provides three tabs:

• Installed — manage currently installed plugins
• Browse — search the registry for new plugins
• Updates — check for and apply plugin updates

Macro System

Chain multiple tools into reusable workflows with {{variable}} templates, single-pass variable expansion (injection-safe), and a maximum of 20 steps. Configure macros in AI Settings > Macros.

Chat Features

• Streaming markdown with finalized/streaming segments and syntax highlighting
• Code block actions — Copy, Apply, Diff, Run buttons on every code block
• Thinking visualization with token count and duration
• Prompt templates — 15 built-in, activated with / prefix
• Chat search (Ctrl+F) with role filter and keyboard navigation
• Conversation branching — fork, switch, delete alternative approaches
• Chat history in SQLite with FTS5 full-text search and retention policies (7/30/90/180/365/unlimited days)
• Export to Markdown or JSON
• Cost tracking per message with monthly budget limits per provider
• Vision/multimodal — drag images into chat or paste from clipboard
• Drag and drop — drag files from the file manager into the chat area for analysis
• Context menu integration — right-click files and select "Ask AeroAgent" to start a conversation about them

Extreme Mode

Available only in Cyber theme. Auto-approves all tool calls for fully autonomous execution with a 50-step limit (vs 10 default). A circuit breaker on consecutive errors provides a safety net.

Warning: Extreme Mode auto-approves all tool calls including destructive operations like remote_delete, local_delete, shell_execute, and server_exec. Use only when you fully trust the AI model.

Architecture

AeroAgent operates in three modes through a shared trait abstraction layer (ai_core/):

This enables GUI mode (Tauri events), CLI mode (stdout/stderr), and Orchestration mode (JSON-RPC 2.0 over stdin/stdout). MCP compatibility maps naturally: tools become MCP Tools, RAG/vault become Resources, macros/templates become Prompts, and multi-step execution becomes Sampling.

Keyboard Shortcuts

AeroPlayer

AeroPlayer is AeroFTP's built-in audio player, designed for previewing audio files directly within the file manager. It uses native HTML5 <audio> with a Web Audio API processing graph for real-time audio manipulation and visualization. AeroPlayer replaced the Howler.js library with a direct Web Audio API architecture for lower latency and finer control over the audio pipeline.

Audio Engine

Audio is routed through a Web Audio API processing graph that applies equalization, stereo panning, and frequency analysis in real-time:

Audio Source → 10-Band EQ → Stereo Panner → Analyser → Destination

A prebuffer strategy ensures smooth playback start by buffering a minimum of 6 seconds of audio data before initiating playback. This prevents stuttering on slower network connections when playing remote files.

Player Interface

The player interface provides standard transport controls (play, pause, stop, seek) alongside the equalizer sliders, stereo balance control, and a visualizer canvas that responds to the audio in real-time.

10-Band Equalizer

Each band uses a dedicated Web Audio BiquadFilterNode for precise frequency shaping. Adjust individual sliders to boost or cut specific frequency ranges, or select a preset for instant configuration.

EQ Presets

Ten built-in presets are available for quick setup:

• Flat — all bands at 0 dB (neutral)
• Bass Boost — enhanced low frequencies
• Treble Boost — enhanced high frequencies
• Vocal — mid-range emphasis for voice clarity
• Rock — scooped mids with boosted lows and highs
• Pop — slight bass and treble lift
• Jazz — warm low-mid emphasis
• Classical — gentle high-frequency lift
• Electronic — sub-bass and treble emphasis
• Loudness — compensates for low-volume listening (bass and treble boost)

Stereo Balance

A StereoPannerNode provides continuous left/right balance control. The panner ranges from -1 (full left) to +1 (full right), with 0 as center. This is useful for compensating asymmetric headphone output or for creative stereo positioning.

Visualizer Modes

AeroPlayer offers 14 visualization modes that respond to the audio in real-time. Press the V key to cycle through all modes while audio is playing.

Canvas 2D Modes (8 modes)

Standard 2D visualizations rendered on an HTML5 Canvas:

WebGL 2 Modes (6 modes)

GPU-accelerated shader-based visualizations that create immersive audio-reactive graphics. These run entirely on the GPU via WebGL 2 fragment shaders, ported from the CyberPulse visualization engine:

Tip: Press V to cycle through all 14 visualizer modes. WebGL modes require GPU support and are automatically skipped on systems without WebGL 2 capability.

Beat Detection

AeroPlayer performs real-time onset energy analysis to detect beats in the audio stream. The algorithm uses:

• Circular buffer — stores recent energy samples for comparison
• Exponential decay (factor 0.92) — smooths energy tracking to distinguish genuine beats from sustained loudness
• Onset threshold — a beat is registered when the current energy exceeds the rolling average by a configurable margin

Detected beats trigger synchronized visual effects across all visualizer modes, creating a responsive audio-visual experience.

Post-Processing Effects

All visualizer modes (both Canvas 2D and WebGL) support layered post-processing effects that add cinematic character to the visualization:

Post-processing effects are composited in order: the base visualization renders first, then vignette, chromatic aberration, scanlines, and finally beat-triggered glitch. Effects can be combined for layered visual complexity.

AeroTools

AeroTools is AeroFTP's built-in security toolkit, available exclusively in the Cyber theme. It provides three modules for hashing, encryption, and password generation -- all running locally via Rust commands with zero network access. Every operation executes entirely on your machine; no data is transmitted externally.

Note: AeroTools is only visible when the Cyber theme is active. Switch themes via the theme toggle in the titlebar (cycle: Auto, Light, Dark, Tokyo Night, Cyber).

Hash Forge

Compute and compare cryptographic hashes for files and text. Hash Forge supports five algorithms covering both legacy compatibility and modern performance needs.

Supported Algorithms

Security note: MD5 and SHA-1 are cryptographically broken for collision resistance. They remain available for compatibility with legacy systems that use them for non-security checksums, but should not be relied upon for security-critical verification.

Operations

• Hash text -- enter arbitrary text in the input field and compute its hash with any algorithm. Useful for verifying passwords, API keys, or configuration values.
• Hash file -- select a local file to compute its hash. The file is read in streaming chunks, so even multi-gigabyte files can be hashed without excessive memory usage.
• Compare hashes -- paste two hash values to check whether they match. Hash Forge performs a constant-time comparison and displays a clear match/mismatch result.

CryptoLab

Encrypt and decrypt text using authenticated encryption algorithms. CryptoLab provides a quick way to protect sensitive text snippets without creating a full AeroVault container.

Encryption Algorithms

How It Works

1. Enter a password in the password field. CryptoLab derives a 256-bit encryption key from the password using a secure key derivation function.
2. Type or paste plaintext into the input area and click Encrypt. The ciphertext is displayed as a Base64-encoded string.
3. To decrypt, paste the ciphertext into the input area, enter the same password, and click Decrypt.

Both algorithms provide authenticated encryption: the ciphertext includes an authentication tag that detects any tampering or corruption. If the password is wrong or the ciphertext has been modified, decryption fails with an explicit error rather than producing garbage output.

Warning: CryptoLab is intended for quick ad-hoc encryption of small text snippets (passwords, API keys, notes). For file encryption, use AeroVault which provides a full encrypted container with key wrapping, header integrity, and optional cascade encryption.

Password Forge

Generate cryptographically secure passwords and passphrases using a cryptographically secure pseudo-random number generator (CSPRNG).

Random Passwords

Random passwords are generated using the operating system's CSPRNG (OsRng in Rust), ensuring true randomness independent of any deterministic seed.

Configuration options:

• Length -- set the password length (8 to 128 characters)
• Character sets -- toggle uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and symbols (!@#$%^&*...) independently
• Entropy display -- shows the password strength in bits of entropy, calculated from the character set size and length

BIP-39 Passphrases

Generate memorable passphrases using the BIP-39 English word list (2048 words). Each word adds approximately 11 bits of entropy.

• Word count -- select from 4 to 24 words
• Separator -- words are space-separated for readability
• Entropy calculation -- displayed alongside the passphrase (e.g., 6 words = ~66 bits)

Note: At 12 or more words, a disclaimer notes that BIP-39 passphrases of this length are typically associated with cryptocurrency seed phrases. This is informational only -- the words are generated randomly and are not derived from any wallet.

Entropy Calculator

Paste any existing string to calculate its Shannon entropy in bits. This helps evaluate the strength of passwords you have already created or received from other generators. The calculator analyzes the character distribution and reports the effective entropy, which may be lower than the theoretical maximum if the password contains patterns or repeated characters.

File Tags

AeroFTP supports Finder-style color labels for organizing local files. Tags provide a visual categorization system that works across directories, letting you mark files for review, flag important assets, or create ad-hoc groupings without moving files into folders. Tags are stored in a local SQLite database and persist across sessions.

Color Labels

Seven preset color labels are available, matching the macOS Finder convention:

Each file can have multiple tags applied simultaneously, and the suggested uses above are purely conventions -- you can use any color for any purpose.

Tagging Files

Context Menu

Right-click a file or selection to access the Tags submenu. Each color label appears as a toggle: click to apply, click again to remove. The submenu also includes a Clear All Tags option to remove all labels from the selected files at once.

Batch Tagging

Select multiple files (Ctrl+Click or Shift+Click), then right-click and use the Tags submenu. The selected tag is applied to all selected files simultaneously. This makes it efficient to categorize a group of related files in a single operation.

Tag Toggle Behavior

Tags use toggle semantics: if a file already has a particular color label, selecting that label again removes it. This provides a quick way to untag files without navigating to a separate "remove" action.

Visual Indicators

Tagged files display colored dot badges directly in the file list, providing immediate visual identification without opening a context menu or properties dialog.

Badge Display Rules

• Up to 3 dots are shown inline next to the filename, each in its respective label color
• Files with more than 3 tags display a "+N" overflow indicator showing how many additional tags are applied
• Badges appear in both list view and grid view
• Badge rendering uses React.memo for performance, preventing unnecessary re-renders when scrolling through large file lists

Sidebar Filter

The Places Sidebar includes a dedicated Tags section that lists all seven color labels with their respective file counts. This provides a powerful cross-directory view of categorized files.

Filtering by Tag

Click any label in the sidebar Tags section to filter the file list. When a tag filter is active:

• The file list shows only files that have the selected tag, regardless of which directory they reside in
• The active filter is visually highlighted in the sidebar
• Click the same label again to clear the filter and return to the normal directory view

This makes it easy to find all files you have flagged as "urgent" (Red) or "ready to deploy" (Green) across your entire local file tree without navigating to each directory individually.

Storage

Tags are stored in a SQLite database using WAL (Write-Ahead Logging) mode for concurrent read performance. The database is created automatically on first use and lives in the AeroFTP application data directory.

Technical Details

• 9 Tauri commands provide the full CRUD interface: add label, remove label, get labels for file, get labels for multiple files (batch), set labels, clear labels, get all labels with counts, and batch operations
• Debounced batch queries (150 ms) in the useFileTags hook reduce database round-trips when browsing directories with many tagged files
• Map cache in the frontend provides instant lookup of tag data for visible files
• WAL mode allows concurrent reads during writes, preventing UI freezes when tagging files while browsing

Scope

Tag data is local-only and is not synchronized to remote servers. Tags are associated with absolute file paths, so moving or renaming a file outside of AeroFTP will disassociate it from its tags. Renaming or moving files within AeroFTP preserves tag associations.

Tip: Use tags to create workflow states (Red = needs review, Green = approved) or to mark files across multiple directories for a batch operation. The sidebar filter makes it easy to collect tagged files from anywhere in your file tree.

Archives

AeroFTP includes a full archive management system for browsing, creating, and extracting compressed archives. Both local and remote archives are supported across all 22 protocols. The system handles seven archive formats with optional AES-256 encryption for ZIP and 7z.

Supported Formats

Archive Browser

Double-click any archive (local or remote) to open the Archive Browser. The browser displays the archive contents in a navigable file tree without extracting the entire archive to disk.

Browsing Features

• Directory navigation -- browse into folders within the archive as if it were a regular directory tree
• File metadata -- view file sizes (both compressed and uncompressed), modification dates, and compression ratios for each entry
• Sorting -- click column headers to sort by name, size, date, or compression ratio
• Selective extraction -- select individual files or folders and extract only those items, without unpacking the entire archive

Remote Archives

When you double-click an archive on a remote server, AeroFTP downloads the archive to a temporary location and opens it in the Archive Browser. This works across all 22 supported protocols.

Creating Archives

Right-click one or more files or directories and select Compress to open the CompressDialog.

Step-by-Step

1. Select files -- choose one or more files or directories in the file list. The dialog displays the total file count and estimated uncompressed size.
2. Choose format -- select the output format from the dropdown: ZIP, 7z, TAR, GZ, XZ, or BZ2.
3. Set compression level -- adjust the compression slider where applicable. Higher levels produce smaller files but take longer to compress.
4. Set a password (optional) -- for ZIP and 7z formats, enter a password to encrypt the archive contents. The password field includes a show/hide toggle.
5. Review and compress -- verify the summary (file count, format, encryption status) and click Compress to create the archive.

Encryption Details

• ZIP encryption uses the WinZip AE-2 standard with AES-256. This is compatible with most modern archive tools (7-Zip, WinRAR, macOS Archive Utility, and others).
• 7z encryption uses the native 7z AES-256 encryption header, which encrypts both file contents and filenames. This provides stronger metadata protection than ZIP, where filenames remain visible even when encrypted.

Security note: ZIP passwords are handled with the secrecy crate and zeroized from memory after use, preventing password leakage through memory dumps.

Encrypted Archives

When opening a password-protected archive, AeroFTP prompts for the password before displaying the contents.

7z Password Detection

Detecting whether a 7z archive is encrypted is non-trivial because the format does not expose a simple encryption flag in its header. AeroFTP uses a content probe approach via for_each_entries to reliably identify encrypted archives: if iterating entries fails with an encryption error, the password prompt is shown.

ZIP Password Detection

ZIP archives include encryption flags in their local file headers, making detection straightforward. AeroFTP checks these flags before attempting extraction.

AeroAgent Integration

AeroAgent includes two archive tools that let you create and extract archives using natural language:

Examples

• "Compress all .log files in /var/log into a password-protected ZIP"
• "Extract the backup.7z archive to ~/restored/"
• "Create a tar.gz of the src/ directory"

AeroAgent selects the appropriate format, handles password prompts, and reports the result with file count and compressed size.

Format Selection Guide

Batch Rename

AeroFTP provides a batch rename dialog for renaming multiple files at once, plus inline rename for quick single-file edits.

Batch Rename Dialog

Select multiple files, then right-click and choose Batch Rename to open the dialog. Four rename modes are available:

Live Preview

As you type, a preview column shows the result of the rename operation for every selected file. This lets you verify the outcome before committing any changes.

Sequential Options

When using Sequential mode, you can configure:

• Base name — the prefix before the number
• Start number — the first number in the sequence (default: 1)
• Zero padding — number of digits (e.g., 3 digits gives 001, 002, ...)

Inline Rename

For renaming a single file quickly:

• F2 — press F2 with a file selected to enter inline edit mode
• Click on filename — click the filename text of an already-selected file

Inline rename works in both the local and remote file panels. Press Enter to confirm or Escape to cancel.

Tip: Batch Rename and Inline Rename are also available through AeroAgent. Ask something like "Rename all .jpeg files to .jpg" and the local_batch_rename tool handles it automatically.

Code Editor

AeroFTP includes an integrated code editor powered by Monaco Editor (the same engine behind VS Code). It supports syntax highlighting for all major languages, multiple themes, and direct integration with AeroAgent.

Opening Files

Double-click any text file in the local or remote file panel to open it in the editor. Remote files are downloaded to a temporary location for editing. On save, remote files are automatically uploaded back to the server.

Features

• Syntax highlighting — auto-detected by file extension, covering 50+ languages
• Multiple themes — editor theme syncs with the application theme:

• Find and replace — standard Ctrl+F / Ctrl+H with regex support
• Minimap — code overview on the right side of the editor
• Word wrap — toggle via the View menu
• Line numbers and bracket matching

AeroAgent Integration

The code editor connects to AeroAgent in two ways:

Ask AeroAgent (Ctrl+Shift+A)

Select code in the editor, then press Ctrl+Shift+A (or right-click > Ask AeroAgent) to send the selection to the AI chat with context. AeroAgent can explain, refactor, or debug the selected code.

Live Sync

When AeroAgent modifies a file using the local_edit or local_write tools, the editor reloads automatically via a file-changed / editor-reload event bridge. This keeps the editor in sync during AI-driven editing sessions.

Technical Notes

Monaco Editor is loaded via AMD modules (not ESM) for compatibility with WebKitGTK on Linux. A Vite plugin copies the required Monaco assets from node_modules/monaco-editor/min/vs/ to the build output during development and production builds.

Tip: The editor is part of the AeroTools panel (alongside the Terminal and AeroAgent chat). Resize panels by dragging the dividers between them.

Terminal

AeroFTP includes an integrated terminal emulator powered by xterm.js, providing a full PTY (pseudo-terminal) directly within the application.

Features

• Full PTY support — run any shell command, interactive programs, and TUI applications
• SSH sessions — connect to remote servers via SSH directly in the terminal tab
• Copy/paste — standard terminal clipboard operations
• Scrollback buffer — scroll through command history
• Resizable — drag the panel divider to adjust terminal height

Theme Auto-Sync

The terminal theme automatically matches the active application theme:

If you manually set a terminal theme, AeroFTP remembers your override and stops auto-syncing until the override is cleared.

AeroAgent Integration

AeroAgent can execute shell commands via the shell_execute backend tool. Commands run in a Rust Command process (not the frontend terminal) with:

• 30-second timeout per command
• 1 MB output limit to prevent memory issues
• Backend denylist — dangerous commands (e.g., rm -rf /, mkfs, dd) are rejected at the Rust level before execution
• stdout/stderr/exit_code captured and returned to the AI

Note: On Linux (WebKitGTK), the terminal requires allowTransparency: false for correct rendering. This is set automatically.

Keyboard Shortcuts

Standard terminal shortcuts apply within the terminal panel. The terminal captures all keyboard input when focused — use Ctrl+Shift+A to break out and send a selection to AeroAgent.

CLI Installation

The aeroftp command-line interface is a standalone Rust binary built from the same codebase as the AeroFTP desktop application. It provides full scriptable access to all 22 supported protocols — FTP, FTPS, SFTP, WebDAV, S3, Google Drive, Dropbox, OneDrive, MEGA, Box, pCloud, Azure Blob, 4shared, Filen, Zoho WorkDrive, Internxt, kDrive, Koofr, Jottacloud, FileLu, Yandex Disk, and OpenDrive — without requiring a graphical environment.

Included with Every Desktop Package

The CLI binary ships inside every AeroFTP desktop package. No separate installation step is required. After installing the desktop app, the binary is available at the following paths:

The binary name is aeroftp-cli. On .deb and .rpm installs, a symlink aeroftp pointing to aeroftp-cli is created in /usr/bin/, so both names work interchangeably:

# Both are equivalent on .deb/.rpm installs
aeroftp --version
aeroftp-cli --version

For package formats where the binary is not in PATH (AppImage, macOS .dmg), create a symlink manually:

# macOS
sudo ln -s /Applications/AeroFTP.app/Contents/MacOS/aeroftp-cli /usr/local/bin/aeroftp

# AppImage — extract first, then symlink
./AeroFTP-x86_64.AppImage --appimage-extract
sudo ln -s "$(pwd)/squashfs-root/usr/bin/aeroftp-cli" /usr/local/bin/aeroftp

Verify Installation

After installing, confirm the CLI is working:

aeroftp --version
# Output: aeroftp-cli 3.0.1

aeroftp --help
# Output: full command listing with descriptions

The --help flag works on every subcommand:

aeroftp ls --help
aeroftp sync --help
aeroftp batch --help

Build from Source

Prerequisites

• Rust toolchain 1.75 or later (install via rustup.rs)
• System libraries (Linux only):
  • libssl-dev (or openssl-devel on Fedora/RHEL)
  • pkg-config

Build Commands

git clone https://github.com/axpnet/aeroftp.git
cd aeroftp/src-tauri
cargo build --release --bin aeroftp-cli

The compiled binary will be at target/release/aeroftp-cli (or target\release\aeroftp-cli.exe on Windows). Copy it to a directory in your PATH:

sudo cp target/release/aeroftp-cli /usr/local/bin/aeroftp

Build Only the CLI (Skip Desktop App)

The CLI is defined as a separate [[bin]] target in Cargo.toml. The cargo build --bin aeroftp-cli command compiles only the CLI binary and its dependencies, without pulling in Tauri or any GUI-related crates.

Color, TTY, and Pipe Behavior

The CLI automatically adapts its output based on the terminal environment:

NO_COLOR Standard

AeroFTP follows the no-color.org convention. Setting the NO_COLOR environment variable (to any value) disables all ANSI color codes and progress bar rendering:

# Disable colors globally
export NO_COLOR=1
aeroftp ls sftp://user@host/

# Or per-command
NO_COLOR=1 aeroftp ls sftp://user@host/

The CLICOLOR variable is also respected. When CLICOLOR=0, colors are suppressed.

Progress Bar Behavior

File transfer progress bars (powered by the indicatif crate) are shown only when:

1. stdout is connected to a TTY
2. Colors are not disabled

In CI/CD environments or when piping output, use --json for machine-readable progress instead.

SIGPIPE Handling

On Unix systems, the CLI installs a SIGPIPE handler at startup via libc::signal(SIGPIPE, SIG_DFL). This ensures proper pipe compliance — if you pipe output to a program that closes early (e.g., head), the CLI terminates cleanly instead of printing a broken pipe error:

# Works correctly — CLI exits when head has enough lines
aeroftp ls sftp://user@host/ --json | head -5

This follows POSIX convention and matches the behavior of standard Unix tools like ls, cat, and find.

Exit Codes

The CLI uses semantic exit codes for scripting:

aeroftp connect sftp://user@host
echo $?  # 0 if successful, 1 if unreachable, 6 if auth failed

Double Ctrl+C

The first Ctrl+C sends a graceful cancellation signal, allowing in-progress transfers to clean up. A second Ctrl+C within 2 seconds forces immediate exit with code 130. This prevents the CLI from hanging if a server is unresponsive during shutdown.

CLI Commands

Complete reference for the aeroftp-cli binary. It shares the same Rust backend as the desktop app, supporting 23 protocols through 14 subcommands with consistent behavior, structured JSON output, and Unix pipeline compatibility.

Connection Methods

URL Format

protocol://user:password@host:port/path

14 protocols support direct URL connections:

9 OAuth providers (Google Drive, Dropbox, OneDrive, Box, pCloud, Zoho WorkDrive, Yandex Disk, 4shared, kDrive) require --profile — authorize once in the GUI, then reuse in the CLI.

Server Profiles (--profile)

Connect to any saved server from the encrypted vault with zero credentials exposed in shell history or process lists.

# List all saved profiles
aeroftp profiles

# Connect by name (fuzzy substring matching)
aeroftp ls --profile "My Server" /path/

# Connect by index number
aeroftp ls --profile 3 /

Profile matching order: exact name (case-insensitive), exact ID (UUID), substring match (auto-selects if unique, lists candidates if ambiguous).

Password Handling

In order of preference:

1. stdin (most secure): echo "$PASS" | aeroftp --password-stdin connect sftp://user@host
2. Environment variable: AEROFTP_TOKEN=mytoken aeroftp connect jottacloud://user@host
3. Interactive prompt: Hidden TTY input when no password provided
4. URL (least secure): sftp://user:password@host — warning always displayed

Master password for vault: set AEROFTP_MASTER_PASSWORD env var or enter interactively.

Commands

connect

Test connectivity, display server info, and disconnect.

aeroftp connect sftp://user@host
aeroftp connect sftp://user@host --key ~/.ssh/id_ed25519
aeroftp connect ftp://user@host --tls explicit --insecure

ls

aeroftp ls sftp://user@host /var/www/ -l          # Long format
aeroftp ls sftp://user@host / --sort size --reverse
aeroftp ls --profile "NAS" / --all --json

get / put

# Download with glob pattern
aeroftp get sftp://user@host "/data/*.csv"

# Recursive download
aeroftp get sftp://user@host /var/www/ ./backup/ -r

# Upload with glob
aeroftp put sftp://user@host "./*.json" /data/

# Recursive upload
aeroftp put sftp://user@host ./dist/ /var/www/dist/ -r

mkdir / rm / mv

aeroftp mkdir sftp://user@host /var/www/new-folder
aeroftp rm sftp://user@host /tmp/old-dir/ -rf
aeroftp mv sftp://user@host /docs/draft.md /docs/final.md

cat / stat / find / df / tree

aeroftp cat sftp://user@host /etc/config.ini | grep DB_HOST
aeroftp stat sftp://user@host /var/www/index.html --json
aeroftp find sftp://user@host /var/www/ "*.php"
aeroftp df sftp://user@host
aeroftp tree sftp://user@host /var/www/ -d 2

sync

aeroftp sync sftp://user@host ./local/ /remote/ --dry-run
aeroftp sync sftp://user@host ./local/ /remote/ --delete   # Mirror mode

batch

Execute .aeroftp script files with 17 commands, shell-like variable substitution, and error policies.

aeroftp batch deploy.aeroftp

# deploy.aeroftp
SET SERVER=sftp://deploy@prod.example.com:2222
SET ON_ERROR=stop

CONNECT ${SERVER}
PUT ./dist/app.js /var/www/app.js
PUT ./dist/index.html /var/www/index.html
STAT /var/www/index.html
ECHO Deployment complete
DISCONNECT

Batch commands: SET, ECHO, CONNECT, DISCONNECT, LS, GET, PUT, MKDIR, RM, MV, CAT, STAT, FIND, DF, TREE, SYNC, SLEEP, EXIT. Variables use ${VAR} syntax with single-pass expansion (injection-safe). Error policies: stop (default), continue.

GitHub Protocol

Every upload and delete creates a real Git commit. Branch-aware with automatic working branch creation for protected branches.

aeroftp ls github://token:PAT@owner/repo@develop /src/ -l
aeroftp put github://token:PAT@owner/repo ./fix.py /src/fix.py
aeroftp cat github://token:PAT@owner/repo /README.md

Global Flags

Output Hygiene

The CLI follows Unix conventions: stdout carries data only (file listings, content, JSON), stderr carries messages (progress bars, summaries, connection status). This makes piping safe:

aeroftp ls sftp://user@host / --json 2>/dev/null | jq '.entries[].name'
aeroftp cat sftp://user@host /data.csv > output.csv 2>/dev/null

Respects NO_COLOR, CLICOLOR, and CLICOLOR_FORCE environment variables.

Exit Codes

CI/CD Example

# GitHub Actions deployment
- name: Deploy to server
  env:
    DEPLOY_PASS: ${{ secrets.DEPLOY_PASSWORD }}
  run: |
    echo "$DEPLOY_PASS" | aeroftp --password-stdin put \
      sftp://deploy@prod.example.com ./dist/ /var/www/ -r

For OAuth providers in CI, use --profile with the vault pre-configured on the runner:

AEROFTP_MASTER_PASSWORD=${{ secrets.VAULT_PW }} \
  aeroftp sync --profile "Production S3" ./build/ / --delete

Batch Scripting

AeroFTP CLI includes a built-in batch scripting engine for automating multi-step file operations. Batch scripts use the .aeroftp file extension and provide variables, error policies, quoting, and all core CLI operations in a simple line-oriented format.

Running a Batch Script

aeroftp batch deploy.aeroftp
aeroftp batch backup.aeroftp --verbose
aeroftp batch script.aeroftp --json

When --json is specified, all command output within the script is emitted as structured JSON to stdout, with errors going to stderr.

Script Format

Each line contains exactly one command. Blank lines and lines starting with # are ignored as comments.

# This is a comment
SET host=sftp://admin@myserver.com

# Blank lines are fine for readability

CONNECT $host
LS $host/var/www/

All 17 Commands

Variable Expansion

Defining Variables

Use SET to define variables. Variable names support alphanumeric characters and underscores:

SET host=sftp://deploy@prod.example.com
SET remote_path=/var/www/html
SET local_path=./dist
SET version=2.5.0

Referencing Variables

Reference variables with $name or ${name}:

ECHO Deploying version $version to $host
PUT $host$remote_path/ $local_path/ -r
GET $host/backups/db-$version.sql.gz -o ./backup.sql.gz

Expansion Rules

• Single-pass expansion: Variables are expanded exactly once. There is no recursive expansion, which prevents injection attacks where a variable value contains $ references.
• Undefined variables: If a variable is not defined, the $name literal is left as-is in the command string.
• Literal dollar sign: Use $$ to produce a literal $ character.

SET price=100
ECHO The cost is $$${price}   # Output: The cost is $100
ECHO Undefined: $missing       # Output: Undefined: $missing

Maximum Variables

A single script may define up to 256 variables. Exceeding this limit causes the script to abort with an error.

Quoting

The batch engine uses shell-like quoting rules:

Double quotes are essential when paths or filenames contain spaces:

SET server=sftp://user@host
PUT $server/uploads/ "Q1 Report (Final).pdf"
GET $server"/path with spaces/data.csv" -o ./data.csv

Error Handling

ON_ERROR Policies

Control how the script reacts when a command fails:

ON_ERROR FAIL       # Abort the entire script on any error
ON_ERROR CONTINUE   # Log the error and proceed to the next line

The default policy is CONTINUE (changed from FAIL as of v2.9.2). You can switch policies at any point in the script, which allows critical sections to abort while optional operations continue:

# Critical: must succeed
ON_ERROR FAIL
CONNECT $server
SYNC $server/www/ ./dist/

# Optional: failure is acceptable
ON_ERROR CONTINUE
GET $server/var/log/access.log -o ./logs/access.log
GET $server/var/log/error.log -o ./logs/error.log

# Critical again
ON_ERROR FAIL
ECHO Deploy verification...
LS $server/www/index.html

Exit Codes

When a script aborts due to ON_ERROR FAIL, the CLI exits with the exit code of the failed command (see Installation for the full exit code table).

Script Limits

Real-World Example: Nightly Backup

# backup.aeroftp — Nightly backup of production server
# Run: aeroftp batch backup.aeroftp
# Cron: 0 2 * * * /usr/bin/aeroftp batch /opt/scripts/backup.aeroftp >> /var/log/aeroftp-backup.log 2>&1

SET server=sftp://backupuser@prod.example.com
SET remote=/var/www/html
SET backup_dir=./backups/nightly

# Critical: database and website must succeed
ON_ERROR FAIL
ECHO [1/4] Connecting to production server...
CONNECT $server

ECHO [2/4] Syncing website files...
SYNC $server$remote/ $backup_dir/www/

ECHO [3/4] Downloading database dump...
GET $server/var/backups/db-latest.sql.gz -o $backup_dir/db-latest.sql.gz

# Optional: logs are nice to have but not critical
ON_ERROR CONTINUE
ECHO [4/4] Downloading server logs...
GET $server/var/log/nginx/access.log -o $backup_dir/access.log
GET $server/var/log/nginx/error.log -o $backup_dir/error.log

ECHO Checking remote disk usage...
DF $server/

ECHO Backup complete.

Schedule it via cron:

# crontab -e
0 2 * * * /usr/bin/aeroftp batch /opt/scripts/backup.aeroftp >> /var/log/aeroftp-backup.log 2>&1

Real-World Example: Multi-Server Deployment

# deploy.aeroftp — Deploy build artifacts to 3 servers
# Run: aeroftp batch deploy.aeroftp

SET build_dir=./dist
SET app_path=/var/www/app

SET staging=sftp://deploy@staging.example.com
SET prod_eu=sftp://deploy@eu.prod.example.com
SET prod_us=sftp://deploy@us.prod.example.com

ON_ERROR FAIL

ECHO === Deploying to staging ===
CONNECT $staging
SYNC $staging$app_path/ $build_dir/ -r

ECHO === Deploying to EU production ===
CONNECT $prod_eu
SYNC $prod_eu$app_path/ $build_dir/ -r

ECHO === Deploying to US production ===
CONNECT $prod_us
SYNC $prod_us$app_path/ $build_dir/ -r

ECHO All 3 servers deployed successfully.

CI/CD Example: GitHub Actions

name: Deploy via AeroFTP Batch

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install AeroFTP CLI
        run: |
          wget -q https://github.com/axpnet/aeroftp/releases/latest/download/aeroftp_amd64.deb
          sudo dpkg -i aeroftp_amd64.deb

      - name: Build project
        run: npm ci && npm run build

      - name: Create batch script
        run: |
          cat > deploy.aeroftp << 'SCRIPT'
          SET server=sftp://${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}
          SET remote=/var/www/html

          ON_ERROR FAIL
          CONNECT $server
          SYNC $server$remote/ ./dist/
          ECHO Deploy complete.
          SCRIPT

      - name: Deploy
        run: aeroftp batch deploy.aeroftp --json
        env:
          NO_COLOR: 1

Tip: Always use ON_ERROR FAIL for critical operations and switch to ON_ERROR CONTINUE for optional steps. This gives fine-grained control over script abort behavior without needing conditional logic.

CLI Examples

Practical recipes for common AeroFTP CLI workflows, covering basic operations, advanced patterns, CI/CD integration, and multi-protocol usage.

Connection URL Format

All CLI commands use URL-based connection strings:

protocol://user[:password]@host[:port]/path

Warning: Embedding passwords in URLs is discouraged — they appear in shell history and process listings. The CLI will warn unconditionally when a password is detected in the URL. Use SSH keys for SFTP, or let the CLI prompt interactively.

Basic File Operations

Download Files

# Download a single file to the current directory
aeroftp get sftp://user@host/reports/quarterly.pdf

# Download to a specific local path
aeroftp get sftp://user@host/reports/quarterly.pdf -o ./downloads/q1.pdf

# Recursive download of an entire directory
aeroftp get sftp://user@host/project/src/ -r -o ./local-src/

Upload Files

# Upload a single file
aeroftp put sftp://user@host/uploads/ ./invoice.pdf

# Upload all CSV files using glob pattern
aeroftp put sftp://user@host/data/ "./*.csv"

# Recursive upload of a directory
aeroftp put sftp://user@host/var/www/ ./dist/ -r

Glob Pattern Transfers

The CLI supports glob patterns (powered by the globset crate) for both uploads and downloads:

# Upload all CSV files from current directory
aeroftp put sftp://user@host/data/ "*.csv"

# Upload all images recursively
aeroftp put sftp://user@host/media/ "**/*.{jpg,png,gif}" -r

# Download all log files
aeroftp get sftp://user@host/var/log/ -r -o ./logs/ --include "*.log"

List, View, and Manage

# List files with details (size, date, permissions)
aeroftp ls sftp://user@host/var/www/ --long

# View a remote file without downloading
aeroftp cat sftp://user@host/etc/nginx/nginx.conf

# Get file metadata
aeroftp stat sftp://user@host/data/export.csv

# Rename a file on the server
aeroftp mv sftp://user@host/docs/draft.md sftp://user@host/docs/published.md

# Delete a remote file
aeroftp rm sftp://user@host/tmp/old-backup.tar.gz

# Create a remote directory
aeroftp mkdir sftp://user@host/var/www/new-project/

Directory Operations

# Show directory tree (3 levels deep)
aeroftp tree sftp://user@host/var/www/ -d 3

# Find all log files recursively
aeroftp find sftp://user@host/var/log/ "*.log"

# Find files modified in the last 7 days
aeroftp find sftp://user@host/data/ "*.csv" --newer 7d

# Check storage quota and disk usage
aeroftp df sftp://user@host/

# Synchronize directories
aeroftp sync sftp://user@host/var/www/html/ ./dist/

JSON Output for Scripting

Every command supports the --json flag for machine-readable structured output. In JSON mode, results go to stdout and errors go to stderr as JSON objects, keeping piped output clean.

# List files as JSON and filter with jq
aeroftp ls sftp://user@host/ --json | jq '.[] | select(.size > 1048576) | .name'

# Get file metadata as JSON
aeroftp stat sftp://user@host/data/export.csv --json
# Output: {"name":"export.csv","size":4521984,"modified":"2026-03-15T14:30:00Z","permissions":"rw-r--r--"}

# Check storage quota programmatically
aeroftp df s3://key@s3.amazonaws.com/my-bucket/ --json | jq '.used_percent'

# List and count files per extension
aeroftp ls sftp://user@host/data/ --json | jq -r '.[].name' | awk -F. '{print $NF}' | sort | uniq -c | sort -rn

# Parse errors in JSON mode (errors go to stderr)
aeroftp get sftp://user@host/missing.txt --json 2>error.json

Directory Synchronization

# Mirror local website to remote server
aeroftp sync sftp://user@host/var/www/html/ ./dist/

# Sync from S3 bucket to local directory
aeroftp sync s3://AKIAIOSFODNN7@s3.eu-west-1.amazonaws.com/assets/ ./local-assets/

# Sync with checksum verification
aeroftp sync sftp://user@host/data/ ./data/ --verify full

# Dry run — show what would change without transferring
aeroftp sync sftp://user@host/www/ ./dist/ --dry-run

Working with Different Protocols

The same commands work identically across all supported protocols:

# SFTP (SSH)
aeroftp ls sftp://user@host/var/www/

# FTP with explicit TLS
aeroftp ls ftps://user@ftp.example.com/

# Plain FTP (not recommended — credentials sent in cleartext)
aeroftp ls ftp://user@ftp.example.com/

# WebDAV (Nextcloud)
aeroftp ls webdav://user@cloud.example.com/remote.php/dav/files/user/

# WebDAV (Seafile)
aeroftp ls webdav://user@seafile.example.com/seafdav/

# S3 (AWS)
aeroftp ls s3://AKIAIOSFODNN7@s3.us-east-1.amazonaws.com/my-bucket/

# S3-compatible (MinIO)
aeroftp ls s3://minioadmin:minioadmin@localhost:9000/my-bucket/

# S3-compatible (Cloudflare R2)
aeroftp ls s3://key@account-id.r2.cloudflarestorage.com/bucket/

# Google Drive (requires prior OAuth setup in desktop app)
aeroftp ls gdrive://me@drive/

# Dropbox (requires prior OAuth setup)
aeroftp ls dropbox://me@dropbox/

# OneDrive (requires prior OAuth setup)
aeroftp ls onedrive://me@onedrive/

CI/CD Integration

GitHub Actions Deployment

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm ci && npm run build

      - name: Install AeroFTP CLI
        run: |
          wget -q https://github.com/axpnet/aeroftp/releases/latest/download/aeroftp_amd64.deb
          sudo dpkg -i aeroftp_amd64.deb
          aeroftp --version

      - name: Deploy via SFTP
        run: |
          aeroftp sync \
            sftp://${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}/var/www/html/ \
            ./dist/ \
            --json
        env:
          NO_COLOR: 1

      - name: Verify deployment
        run: |
          aeroftp ls sftp://${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}/var/www/html/ --json | jq length

GitLab CI

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - npm ci && npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  image: ubuntu:22.04
  before_script:
    - apt-get update && apt-get install -y wget
    - wget -q https://github.com/axpnet/aeroftp/releases/latest/download/aeroftp_amd64.deb
    - dpkg -i aeroftp_amd64.deb
  script:
    - aeroftp put sftp://${DEPLOY_USER}@${DEPLOY_HOST}/releases/ ./dist/app.tar.gz
    - aeroftp ls sftp://${DEPLOY_USER}@${DEPLOY_HOST}/releases/ --json
  environment:
    name: production

Connection Testing in CI

#!/bin/bash
# pre-deploy-check.sh — Verify server is reachable before deploying

aeroftp connect sftp://ci@staging.example.com
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "Server unreachable (exit code: $EXIT_CODE), aborting deploy"
  exit 1
fi

echo "Server reachable, proceeding with deploy..."
aeroftp sync sftp://ci@staging.example.com/www/ ./dist/

Monitoring: Storage Quota Alert

#!/bin/bash
# quota-check.sh — Alert when storage exceeds 80%

USAGE=$(aeroftp df s3://key@s3.amazonaws.com/my-bucket/ --json | jq -r '.used_percent')

if (( $(echo "$USAGE > 80" | bc -l) )); then
  echo "WARNING: Storage at ${USAGE}% — consider cleanup"
  # Send alert via webhook, email, etc.
  curl -X POST "$SLACK_WEBHOOK" -d "{\"text\":\"Storage alert: ${USAGE}% used\"}"
fi

Batch Script: Multi-Server Deployment

# deploy-all.aeroftp — Deploy to staging + production
# Run: aeroftp batch deploy-all.aeroftp

SET build=./dist
SET app=/var/www/app

SET staging=sftp://deploy@staging.example.com
SET prod_eu=sftp://deploy@eu.prod.example.com
SET prod_us=sftp://deploy@us.prod.example.com

ON_ERROR FAIL

ECHO [1/3] Deploying to staging...
SYNC $staging$app/ $build/
ECHO Staging deploy complete.

ECHO [2/3] Deploying to EU production...
SYNC $prod_eu$app/ $build/
ECHO EU deploy complete.

ECHO [3/3] Deploying to US production...
SYNC $prod_us$app/ $build/
ECHO US deploy complete.

ECHO All servers deployed.

aeroftp batch deploy-all.aeroftp

Batch Script: Database Backup Rotation

# db-backup.aeroftp — Download DB dump and rotate old backups

SET server=sftp://backup@db.example.com
SET remote_dump=/var/backups/pg-latest.sql.gz
SET local_dir=./backups

ON_ERROR FAIL
ECHO Downloading latest database dump...
GET $server$remote_dump -o $local_dir/pg-latest.sql.gz

ON_ERROR CONTINUE
ECHO Cleaning up old remote dumps...
RM $server/var/backups/pg-7days-ago.sql.gz

ECHO Checking server disk space...
DF $server/

ECHO Backup complete.

Tips and Best Practices

1. Always test with connect first — verify credentials before running long operations. Connection failures return exit code 1.

2. Use --json in scripts — structured output is stable across versions and safe to parse.

3. Set NO_COLOR=1 in CI — prevents ANSI escape codes from polluting log files.

4. Prefer SFTP over FTP — SFTP encrypts both credentials and data. FTP sends passwords in cleartext.

5. Use batch scripts for multi-step operations — they provide error handling, variables, and reproducibility that shell scripts require extra effort to achieve.

6. Pipe JSON to jq for filtering — aeroftp ls --json | jq '.[] | select(.size > 1000000)' is more reliable than parsing human-readable output.

7. Check exit codes — every CLI command returns a semantic exit code (0 for success, 1-8 for specific failure categories, 99 for unknown errors).

Note: For the complete list of exit codes and their meanings, see the Installation page.

Encryption

AeroFTP uses encryption at multiple layers to protect data at rest, in transit, and during credential storage. All cryptographic operations execute locally in the Rust backend — no data is ever sent to external services for encryption or key management.

Encryption Architecture Overview

AeroFTP applies encryption across four distinct layers:

Each layer operates independently, meaning a vulnerability in one layer does not compromise the others.

AeroVault v2

AeroVault v2 is AeroFTP's proprietary encrypted container format (.aerovault files), designed with a defense-in-depth architecture using seven cryptographic primitives:

Container Format

An AeroVault v2 file has the following structure:

[512-byte header]
  - Magic bytes: "AEROVAULT2"
  - Argon2id salt (32 bytes)
  - Wrapped master key (AES-256-KW)
  - HMAC-SHA512 over header fields

[AES-SIV encrypted manifest]
  - JSON directory listing
  - Per-file metadata (name, size, offset, is_dir)

[Chunked encrypted data]
  - 64 KB chunks, each independently encrypted with AES-256-GCM-SIV
  - Per-chunk random nonce
  - Optional ChaCha20-Poly1305 second layer (cascade mode)

Why AES-256-GCM-SIV

AES-256-GCM-SIV (RFC 8452) is a nonce-misuse-resistant AEAD cipher. Unlike standard AES-GCM, accidental nonce reuse does not catastrophically compromise security — it only leaks whether two plaintexts are identical. This provides a significant safety margin for file encryption where nonce management across thousands of chunks is critical.

Argon2id Parameters

The key derivation parameters exceed OWASP 2024 minimum recommendations:

AeroVault v2 vs Cryptomator

AeroFTP can also open Cryptomator vault format 8 containers as read-only legacy support, using scrypt + AES-256-KW + AES-256-SIV + AES-256-GCM.

Archive Encryption

AeroFTP supports creating and extracting password-protected archives:

Archive passwords are zeroized in memory immediately after use via the secrecy crate's SecretString type. The password is unwrapped only at the point of use (passing to the compression library) and automatically zeroed when the SecretString is dropped.

Credential Storage

All credentials are stored in vault.db, an encrypted SQLite database:

See Credential Management for the full credential lifecycle, import/export, and migration details.

Transport Security

Every protocol uses transport-layer encryption where available:

SFTP Host Key Verification (TOFU)

For SFTP connections, AeroFTP implements Trust On First Use (TOFU) host key verification. On the first connection to a new server, a PuTTY-style dialog displays the SHA-256 fingerprint of the server's host key. The user must explicitly accept the key before the connection proceeds. Subsequent connections verify the stored fingerprint and warn if the key has changed (potential MITM attack).

FTP TLS Downgrade Detection

When connecting via FTP with ExplicitIfAvailable TLS mode, AeroFTP attempts a TLS upgrade. If the upgrade fails (server does not support STARTTLS), the connection falls back to plaintext FTP. In this case, a tls_downgraded flag is set internally and a security warning is logged. The UI displays a TLS badge that dynamically hides when encryption is set to "none".

Warning: Plain FTP transmits credentials and data in cleartext. Always prefer SFTP or FTPS when available.

OAuth Token Protection

OAuth access tokens and refresh tokens for all cloud providers are protected with multiple layers:

1. SecretString wrapping: All token values are wrapped in Rust's secrecy::SecretString across every provider implementation. This prevents tokens from appearing in debug output, logs, or error messages.

2. Vault storage: Tokens are stored encrypted in vault.db (AES-256-GCM) at rest.

3. In-memory fallback: If the vault is locked or unavailable, tokens are held in an in-memory Mutex for the session duration. They are never written to disk unencrypted.

4. Unwrap-at-use: Tokens are only exposed (via .expose_secret()) at the exact point where they are inserted into HTTP request headers.

5. Error sanitization: The sanitize_error_message() function uses 5 compiled regex patterns to strip API keys (Anthropic sk-ant-*, OpenAI sk-*), Bearer tokens, and x-api-key values from any error message before it reaches logs or the UI.

Memory Zeroization

AeroFTP uses the secrecy crate for zero-on-drop semantics on all sensitive values:

• Passwords: Master password, archive passwords, server passwords
• OAuth tokens: Access tokens, refresh tokens
• API keys: AI provider keys (OpenAI, Anthropic, etc.)
• Cryptographic keys: AES keys, HMAC keys, derived keys
• TOTP secrets: 2FA secret bytes (see TOTP 2FA)

When a SecretString or Secret<Vec<u8>> is dropped, the underlying memory is overwritten with zeros before deallocation. This prevents sensitive data from lingering in freed memory where it could be recovered by memory forensics tools.

Credential Management

AeroFTP stores all sensitive data — server passwords, OAuth tokens, API keys, AI provider keys, and application configuration — in an encrypted vault backed by SQLite. This page describes the vault architecture, key derivation, storage scope, import/export, and platform-specific behavior.

Unified Keystore (vault.db)

The primary credential store is vault.db, located in the application data directory:

Database Architecture

Each entry in the vault is individually encrypted with AES-256-GCM using a unique random nonce. This means that even if two entries have identical plaintext values, their ciphertexts differ. The per-entry nonce is stored alongside the ciphertext in the same database row.

Key Derivation Chain

Master Password (user-provided)
  │
  ├─ Argon2id (128 MiB, t=4, p=4, 32-byte salt)
  │    │
  │    └─ Master Key (256-bit)
  │         │
  │         ├─ HKDF-SHA256 (info="vault-encryption")
  │         │    └─ Vault Encryption Key (for AES-256-GCM)
  │         │
  │         ├─ HKDF-SHA256 (info="vault-auth")
  │         │    └─ Authentication Key (for vault unlock verification)
  │         │
  │         └─ HKDF-SHA256 (info="export-key")
  │              └─ Export Key (for .aeroftp-keystore files)

If no master password is set, a 512-bit passphrase is generated using the operating system CSPRNG (OsRng) and stored in the OS keyring. This provides strong encryption without requiring user interaction on every launch.

What Gets Stored

The vault stores the following categories of sensitive data:

Master Password

The master password is optional but strongly recommended. It protects the vault against unauthorized access on shared machines.

With Master Password

• The password is processed through Argon2id (128 MiB, t=4, p=4) to derive the master key
• The master password itself is never stored anywhere — only the derived key is held in memory or the OS keyring
• On each application launch, the user is prompted for the master password
• If TOTP 2FA is enabled, a second factor is required after the password (see TOTP 2FA)

Without Master Password

• A 512-bit passphrase is auto-generated via OsRng (CSPRNG) at first launch
• The passphrase is stored in the OS keyring (keyring crate with linux-native feature)
• The vault unlocks automatically on launch without user interaction
• Security relies on OS-level access control (user login, screen lock)

OS Keyring Integration

AeroFTP uses the keyring crate to interact with the operating system's credential store:

At startup, AeroFTP probes the OS keyring. If available, the vault decryption key is stored there for seamless unlock on subsequent launches. If the keyring is unavailable (headless systems, CI environments, minimal desktop sessions), AeroFTP falls back to in-memory key storage with a password prompt on each launch.

OAuth Token Storage

OAuth tokens follow a two-tier storage strategy:

1. Primary: Stored in vault.db, encrypted at rest with AES-256-GCM
2. Fallback: If the vault is locked or unavailable at the moment of token receipt, tokens are held in an in-memory Mutex for the session duration

Tokens are never written to disk unencrypted. All token values across all 22 provider implementations are wrapped in secrecy::SecretString to prevent accidental logging or debug output. Tokens are unwrapped (.expose_secret()) only at the exact point where they are inserted into HTTP Authorization headers.

Import and Export

AeroFTP supports credential backup and restore via encrypted .aeroftp-keystore files.

Export

1. Open Settings > Servers > Export
2. A checklist dialog appears showing all saved server profiles
3. Select individual servers or use Select All / Deselect All
4. Choose a destination file path
5. Enter an export password (used to encrypt the file)

The export file is encrypted with:

Import

1. Open Settings > Servers > Import
2. Select a .aeroftp-keystore file
3. Enter the export password
4. HMAC is verified before decryption proceeds
5. Credentials are merged into the current vault

Warning: The export file contains all credentials for the selected servers, including passwords and OAuth tokens. Store it securely and delete it after a successful import.

Error Handling

Import and export operations include proper error handling for:

• Vault not initialized (first launch before setup)
• Incorrect export password (HMAC verification failure)
• Corrupted export file
• Missing or inaccessible file paths

All errors are logged with context rather than silently discarded.

Migration Wizard

When upgrading from older AeroFTP versions that stored credentials in localStorage or the OS keyring directly, a 4-step migration wizard runs automatically on first launch:

The wizard is auto-triggered on first launch after an upgrade. It can also be manually invoked from Settings > Security > Re-run Migration.

Windows Credential Persistence

On Windows, vault.db is the authoritative credential store, but localStorage is maintained as a write-through backup. This dual-write strategy prevents permanent credential loss if the Windows Credential Manager encounters issues (corruption, access denied, service restart).

The secureStoreAndClean function is await-ed at all 6 call sites in the frontend to prevent race conditions where the vault returns stale data before the write has completed. This was a critical fix — earlier versions used fire-and-forget writes that could silently lose credentials.

Security Considerations

• Master password never stored: Only a derived key is held in memory or the OS keyring. The raw password cannot be recovered.
• WAL mode: SQLite WAL provides concurrent read access without database corruption, even during power loss.
• Failed auth opacity: Failed authentication attempts do not reveal whether a particular credential exists in the vault.
• Auto-lock: The vault locks automatically when the application closes. There is no configurable timeout — the vault remains unlocked for the entire session.
• No telemetry: Credential operations are never logged to external services. All operations are local-only.
• Poison recovery: Mutex-protected vault state includes poison recovery, preventing application hangs if a thread panics during a vault operation.

TOTP Two-Factor Authentication

AeroFTP supports an optional TOTP (Time-based One-Time Password) second factor for protecting vault access. When enabled, unlocking the vault requires both the master password and a 6-digit code from an authenticator app, providing defense against stolen or guessed passwords.

Overview

Setup

Enabling TOTP

1. Open Settings > Security
2. Click Enable TOTP 2FA
3. A QR code is displayed containing the TOTP secret in otpauth:// URI format
4. Scan the QR code with your authenticator app
5. Enter the 6-digit verification code shown in your authenticator app to confirm setup
6. TOTP is now active — the vault will require a code on every unlock

The setup_verified gate ensures that TOTP enforcement only activates after the initial verification code is successfully entered. This prevents a misconfigured authenticator from locking the user out of the vault.

Warning: Save your TOTP secret or take a screenshot of the QR code before closing the setup dialog. If you lose access to your authenticator app, you will not be able to unlock the vault. There is no recovery mechanism — the TOTP secret is stored encrypted and cannot be extracted without the current master password and a valid TOTP code.

What the QR Code Contains

The QR code encodes a standard otpauth://totp/ URI:

otpauth://totp/AeroFTP:Vault?secret=BASE32SECRET&issuer=AeroFTP&algorithm=SHA1&digits=6&period=30

Any RFC 6238-compatible authenticator app can scan this code.

Unlock Flow

When TOTP is enabled, the vault unlock sequence is:

1. User enters master password
2. Argon2id derives master key from password
3. Master key is verified against stored authentication hash
4. If password is correct → TOTP input field appears
5. User enters 6-digit code from authenticator app
6. Code is verified against stored TOTP secret (current + previous time window)
7. If code is valid → vault unlocks
8. If code is invalid → attempt counter increments, rate limiting may apply

The TOTP verification accepts codes from the current 30-second window and the immediately preceding window, providing a 60-second effective validity period. This accounts for minor clock drift between the device and the authenticator app.

Rate Limiting

To prevent brute-force attacks on the 6-digit TOTP code (which has only 1,000,000 possible values), AeroFTP enforces exponential backoff on failed attempts:

The rate limiter state is held in memory and resets completely after a successful authentication. Restarting the application also resets the rate limiter (this is intentional — the rate limiter protects against automated attacks during a single session, not against offline attacks which are already mitigated by Argon2id).

Lockout Behavior

During a lockout period:

• The TOTP input field is disabled
• A countdown timer shows the remaining lockout duration
• The master password field remains accessible (but submitting triggers the lockout check)
• No network requests are made during lockout (all verification is local)

Disabling TOTP

1. Open Settings > Security
2. Click Disable TOTP 2FA
3. Enter your current 6-digit TOTP code to confirm identity
4. TOTP is removed — the vault returns to password-only authentication

Disabling TOTP requires a valid current code. This prevents an attacker who knows the master password (but not the TOTP secret) from downgrading the vault's security.

Technical Implementation

Thread Safety

The TOTP state is stored in a Mutex<TotpInner> structure that serializes all TOTP operations. This ensures that concurrent vault unlock attempts (e.g., from multiple UI events) cannot race against each other. The mutex includes poison recovery — if a thread panics while holding the lock, subsequent lock acquisitions recover gracefully instead of propagating the panic.

Cryptographic Properties

Secret Lifecycle

1. Setup initiated → OsRng generates 20 random bytes
2. Secret displayed as QR code → user scans with authenticator app
3. User enters verification code → code validated against secret
4. If valid → secret encrypted and stored in vault.db, setup_verified = true
5. If invalid → secret discarded, setup_verified remains false
6. On vault unlock → secret decrypted from vault.db, used for HMAC-SHA1, then zeroized
7. On TOTP disable → secret permanently deleted from vault.db

At no point is the raw TOTP secret written to disk in plaintext. The Secret<Vec<u8>> wrapper ensures that the bytes are overwritten with zeros when the value is dropped, preventing sensitive data from persisting in freed memory.

Frequently Asked Questions

Can I use TOTP without a master password? No. TOTP is a second factor that supplements the master password. Without a master password, the vault uses an auto-generated passphrase stored in the OS keyring, and TOTP cannot be enabled.

What happens if my authenticator app is lost? There is no recovery mechanism. You will need to reset the vault, which deletes all stored credentials. This is a deliberate security design — TOTP recovery codes would weaken the two-factor guarantee.

Does TOTP protect individual file operations? No. TOTP protects vault access only. Once the vault is unlocked for a session, all operations (file transfers, encryption, credential retrieval) proceed without additional TOTP prompts. The vault remains unlocked until the application is closed.

Is the TOTP implementation audited? The TOTP implementation was reviewed as part of the v2.2.4 security audit (5 independent reviewers). Specific hardening measures include: single Mutex<TotpInner> replacing separate locks, setup_verified gate, exponential rate limiting, OsRng instead of thread_rng, zeroize on all secret bytes, and poison recovery on the mutex.

AI Agent Credential Isolation

As of March 2026, AeroFTP is the only file manager that lets AI coding agents interact with remote servers across 23 protocols without ever exposing credentials.

The Problem

AI coding agents — Claude Code, Cursor, Codex, Devin — need to read and write files on remote servers. Every current approach leaks credentials:

An AI agent that runs scp or sets environment variables places your credentials in its own context window, shell history, process list, and potentially in training data.

How AeroFTP Solves This

AeroFTP introduces a credential isolation boundary between the AI agent and the authentication layer:

1. All credentials are stored in an encrypted vault (AES-256-GCM + Argon2id with 128 MiB memory cost)
2. The agent calls aeroftp ls --profile "My Server" /path/ — no password anywhere in the command
3. The Rust backend opens the vault, authenticates to the remote server, and executes the operation
4. The agent receives only the result (directory listing, file content, transfer confirmation)
5. Credentials never appear in: command-line arguments, environment variables, shell history, IPC messages, AI model context, or application logs

The master password unlocks the vault once per session. After that, every operation uses the stored credentials internally.

CLI: Profile-Based Access

The aeroftp CLI resolves credentials from the vault at runtime. The agent never sees them:

# List saved profiles (names and protocols only, never passwords)
aeroftp profiles

# Standard file operations — credential-free
aeroftp ls --profile "Production" /var/www/
aeroftp put --profile "Staging" ./dist/app.js /var/www/app.js
aeroftp cat --profile "Production" /etc/nginx/nginx.conf
aeroftp sync --profile "NAS Backup" ./data/ /backups/ --dry-run

# OAuth providers work identically — authorize once in the GUI, reuse from CLI
aeroftp ls --profile "Google Drive" /
aeroftp get --profile "Dropbox" /Documents/report.pdf
aeroftp put --profile "OneDrive" ./report.xlsx /Work/

For CI/CD pipelines, a single secret (AEROFTP_MASTER_PASSWORD) unlocks the vault and grants access to all configured servers. No per-server secrets to manage.

AeroAgent: Built-In AI Tools

AeroFTP's integrated AI assistant (AeroAgent) includes two tools specifically designed for credential-isolated server access:

server_list_saved (safe) — Returns server names, protocols, and hostnames. Never returns passwords, tokens, or API keys.

server_exec (high danger, requires approval) — Executes 10 operations on any saved server:

Server matching is fuzzy: exact name, then case-insensitive, then substring. If the match is unique, it proceeds automatically. If ambiguous, it returns the list of candidates and asks for clarification.

Passwords are resolved from the vault in Rust — they cross no IPC boundary, no JavaScript context, and no AI model input.

Protocol Coverage

All 23 protocols supported by AeroFTP work with credential isolation:

Direct authentication (username/password or API key stored in vault): FTP, FTPS, SFTP, WebDAV, S3-compatible, GitHub, Azure Blob, MEGA, Filen, Internxt, kDrive, Jottacloud, FileLu, Koofr, OpenDrive, Yandex Disk

OAuth (authorize once in the GUI, token stored in vault, reused from CLI and AeroAgent): Google Drive, Dropbox, OneDrive, Box, pCloud, Zoho WorkDrive, 4shared

Practical Workflows

Web deployment — An AI agent edits source code locally, then deploys:

aeroftp put --profile "Production" ./dist/ /var/www/html/ --recursive

Multi-server management — Batch scripts reference profiles by name:

SET profile = NAS Backup
CONNECT $profile
PUT ./database-dump.sql /backups/db/
DISCONNECT

Code review with server context — Ask AeroAgent to compare local code with what is deployed:

"Compare my local app.js with the version on Production server at /var/www/app.js"

AeroAgent calls server_exec to read the remote file, diffs it locally, and reports the changes. The production server's SFTP password never enters the conversation.

Why Existing Solutions Fall Short

• Traditional CLIs (scp, rsync, rclone) require credentials in arguments, config files, or environment variables — all accessible to the AI agent
• OS keystores protect against other users, not other processes running as the same user
• Credential proxy services (Vault, AWS Secrets Manager) only handle HTTP-based APIs — they cannot authenticate an FTP or SFTP session
• SSH agent forwarding covers only SSH/SFTP, not the other 20+ protocols

AeroFTP handles all 23 protocols natively behind a single encrypted vault with a single unlock mechanism. The AI agent operates through a narrow, well-defined interface: profile name and file path. Nothing else.

Building from Source

AeroFTP is a Tauri 2 application with a Rust backend and React frontend. Both must be built together for a complete application, but can be developed independently.

Prerequisites

Linux Dependencies

Ubuntu/Debian:

sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Fedora:

sudo dnf install webkit2gtk4.1-devel gtk3-devel libayatana-appindicator-gtk3-devel librsvg2-devel

Arch Linux:

sudo pacman -S webkit2gtk-4.1 gtk3 libayatana-appindicator librsvg

Windows

No additional system dependencies are required. Rust and Node.js are sufficient.

macOS

Install Xcode Command Line Tools:

xcode-select --install

Clone and Install

git clone https://github.com/axpnet/aeroftp.git
cd aeroftp
npm install

Development

Run the full application in development mode (hot-reload for frontend, auto-rebuild for Rust):

npm run tauri dev

Frontend only (no Rust backend, opens in browser):

npm run dev

Rust backend check (no full build):

cd src-tauri && cargo check

Production Build

npm run tauri build

This produces platform-specific packages in src-tauri/target/release/bundle/:

CLI Binary Only

To build just the CLI without the desktop application:

cd src-tauri
cargo build --release --bin aeroftp-cli

The binary will be at src-tauri/target/release/aeroftp-cli.

Linting

Always run Clippy before pushing changes. This is the same check CI runs:

cd src-tauri && cargo clippy --all-targets -- -D warnings

Frontend type checking:

npm run build

i18n Validation

After modifying translation keys, verify all 47 languages are complete:

npm run i18n:validate

To propagate new keys from en.json to all other locales:

npm run i18n:sync

Important: Always run cargo clippy before pushing. The CI pipeline enforces -D warnings (warnings as errors) and will reject non-compliant code.

Architecture

AeroFTP is built on Tauri 2, combining a Rust backend with a React 18 + TypeScript frontend rendered in the system WebView.

High-Level Overview

┌─────────────────────────────────────────────────┐
│                    Frontend                      │
│         React 18 + TypeScript + Tailwind         │
│                  (src/)                           │
├──────────────────────┬──────────────────────────┤
│      Tauri IPC       │     Tauri Events          │
│    invoke() calls    │   emit() / listen()       │
├──────────────────────┴──────────────────────────┤
│                  Rust Backend                     │
│               (src-tauri/src/)                    │
│                                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │Protocols │ │ AI Core  │ │  AeroVault       │ │
│  │(22 impls)│ │(streaming│ │  (AES-256-GCM-   │ │
│  │          │ │ + tools) │ │   SIV + Argon2id)│ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │AeroSync  │ │ Plugins  │ │  Credential      │ │
│  │(journal, │ │(manifest │ │  Vault (SQLite   │ │
│  │ verify)  │ │ + hooks) │ │  + AES-GCM)      │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────┘

Backend (src-tauri/src/)

The Rust backend handles all protocol communication, encryption, and system operations.

Key Modules

Protocol Providers

22 StorageProvider trait implementations, each in its own file:

• Server protocols: FTP/FTPS (ftp.rs), SFTP (sftp.rs), WebDAV (webdav.rs), S3 (s3.rs)
• OAuth2 cloud: Google Drive, Dropbox, OneDrive, Box, pCloud, Zoho WorkDrive, Internxt, kDrive, Koofr, Jottacloud
• API key / session: MEGA, Azure Blob, 4shared (OAuth 1.0), Filen, FileLu, Yandex Disk, OpenDrive

The StorageProvider trait defines 18 methods: connect, disconnect, list, upload, download, delete, rename, mkdir, stat, search, move_file, list_trash, restore_from_trash, permanent_delete, create_share_link, get_storage_quota, list_versions, download_version.

Frontend (src/)

React 18 with TypeScript strict mode, styled with Tailwind CSS. Four themes: Light, Dark, Tokyo Night, Cyber.

Key Components