Vela

A fast, keyboard-driven SFTP client for the terminal

---

Why Vela?

If you ever missed a simple File Transfer Utility, Vela is for you. It lives in your terminal, works over SFTP, and gets out of your way.

• Dual-panel layout — local on the left, remote on the right
• Keyboard-driven — no mouse required
• Saved connection profiles — connect to your servers in seconds
• Lightweight — a single native binary, no Electron, no runtime

---

Screenshots

Manage connection profiles

Edit a connection profile

Execute a shell command in the local directory

Keyboard shortcuts overview (F1)

Remote image preview. Also local. Screenshot is within iTerm2

---

Features

• SFTP support over SSH
• Dual-panel file browser with keyboard navigation
• Saved connection profiles (~/.config/vela/profiles.toml), with optional starting directories for either panel
• Upload, download, rename, delete, and create directories
• Copy files directly between two local directories (left ↔ right panel) before connecting to a server
• Multi-select files with Space and *
• Drag & drop files from Finder onto the window to upload them
• Edit remote files directly — opens in your local editor, uploads on save
• Quick image preview (v) for png/jpg/gif/bmp/webp — local or remote, no need to download first
• Tail the last 50 lines of a remote file (t)
• Execute local shell commands (e.g. make, make deploy) without leaving Vela
• Transfer progress bar with file count
• Encrypted password storage via OS keychain (macOS Keychain / Linux Secret Service)
• Dark / Light / Auto / custom color themes (Ctrl+T to cycle)

---

Installation

Prerequisites

Linux only — Vela uses the D-Bus Secret Service for password storage. Install the required system library before building:

# Debian / Ubuntu
sudo apt install libdbus-1-dev pkg-config

# Fedora
sudo dnf install dbus-devel

# Arch
sudo pacman -S dbus

On macOS no extra dependencies are needed (uses the native Keychain).

From source

Make sure you have Rust installed, then:

git clone https://github.com/staatzstreich/vela.git
cd vela
cargo build --release

The binary will be at target/release/vela. Copy it to your PATH:

cp target/release/vela /usr/local/bin/

Via cargo install (directly from GitHub)

cargo install --git https://github.com/staatzstreich/vela

macOS: arm64, x86_64, and a universal binary

bin/build-macos.sh

Cross-compiles both aarch64-apple-darwin and x86_64-apple-darwin (Xcode's toolchain supports both natively regardless of which Mac you're on — no cross-linker setup needed, unlike the Linux/Windows builds below), then combines them into one fat binary with lipo. Installs any missing rustup target automatically. Output: vela-arm64, vela-x86_64, vela-universal.

Linux, via Docker (no Linux machine needed)

docker build --platform linux/amd64 -f docker/linux-build.Dockerfile -t vela-linux-build .
docker create --name vela-extract vela-linux-build
docker cp vela-extract:/vela/target/release/vela ./vela-linux-x86_64
docker rm vela-extract

Use --platform linux/arm64 for an arm64 Linux binary instead. On Apple Silicon, linux/amd64 runs under Docker's QEMU emulation — slower to build, but a genuine native compile inside the container, not a cross-compile. Requires libdbus-1-dev at build time (installed inside the image already) for the Secret Service password backend.

Windows, via Docker cross-compile (experimental)

docker build -f docker/windows-cross-build.Dockerfile -t vela-windows-build .
docker create --name vela-extract vela-windows-build
docker cp vela-extract:/vela/target/x86_64-pc-windows-gnu/release/vela.exe ./vela-windows-x86_64.exe
docker rm vela-extract

Cross-compiles via mingw-w64 from Linux — no Windows machine needed.

Verified on real Windows 11 (arm64 VM under UTM/QEMU on Apple Silicon, hardware-accelerated — not CPU emulation — tested in both cmd.exe and Windows Terminal): the app starts, raw mode/alternate screen and keyboard input work, panel navigation, the help overlay, theme cycling, and local-to-local copy (F5/F6 before connecting) all function correctly.

Keystrokes feel consistently laggy (~0.5-1s) once Vela is running, in both terminal hosts identically, while plain typing at the cmd.exe prompt (outside Vela, no raw mode) is instant. That isolates it to Windows' ConPTY layer rather than the VM, the CPU, or either terminal app specifically — matching a known, still-open Microsoft issue (microsoft/terminal#13594: ConPTY throttles keystroke input speed) and an identical symptom reported independently for Claude Code's own Windows CLI (anthropics/claude-code#41501: same lag, terminal-agnostic, every other cause ruled out, WSL2 unaffected since it uses the Linux PTY path instead of ConPTY). Not a Vela bug — just a Windows platform limitation for any raw-mode terminal app.

Password storage would use the Windows Credential Manager (keyring's windows-native feature, wired up in Cargo.toml's [target.'cfg(windows)'.dependencies] section) but that path hasn't been exercised yet (no SFTP server was reachable from the test VM).

---

Getting Started

Launch Vela in your terminal:

vela

Press F9 or p to open the profile manager and add your first server connection.

---

Keyboard Shortcuts

Key	Action
↑ / ↓	Move cursor
Tab	Switch panel
Enter	Open directory
Backspace	Go up one directory
Space	Select / deselect file
*	Select / deselect all
F1	Show help
F2	Rename
F3	Disconnect
F4	Edit file in $EDITOR
F5	Upload (connected) / copy left → right (not connected)
F6	Download (connected) / copy right → left (not connected)
F7	Create directory
F8	Delete
F9 / p	Connection profiles
F10 / q	Quit
v	Image preview (png/jpg/gif/bmp/webp)
t	Tail last 50 lines of a remote file
!	Execute shell command in local directory
Ctrl+U / Ctrl+S	Swap panels visually
Ctrl+T	Cycle theme (Auto → Dark → Light → custom themes)
Esc	Close dialog / cancel

---

Configuration

Profiles are stored in ~/.config/vela/profiles.toml:

[[profile]]
name = "My Server"
host = "example.com"
port = 22
user = "deploy"
auth = "key"
key_path = "~/.ssh/id_rsa"
remote_path = "/var/www/html"
local_start_path = "~/projects/my-server"

Set auth = "password" to use password authentication instead of an SSH key. The optional remote_path field sets the initial remote directory after connecting; local_start_path does the same for the local (left) panel.

---

Themes

Ctrl+T cycles Auto → Dark → Light → any custom themes → Auto. The choice is persisted in ~/.config/vela/settings.toml. Auto picks Dark or Light based on your terminal's reported background ($COLORFGBG).

Theme files live in ~/.config/vela/themes/*.toml (dark.toml, light.toml, and a custom.toml starting point are created on first run, and never overwritten). Copy custom.toml under a new name to add another custom theme — it'll show up in the Ctrl+T cycle automatically.

---

Editor Support

Vela looks for an editor in this order:

1. $EDITOR environment variable
2. $VISUAL environment variable
3. vim
4. nano
5. vi

To always use a specific editor, set $EDITOR in your shell profile:

export EDITOR=vim

---

Platform Support

Platform	Status
macOS (arm64 / x86_64 / universal)	✅ Supported
Linux (arm64 / x86_64)	✅ Supported
Windows	⚠️ Experimental — verified working on real Windows 11 (see Building), but keystrokes feel laggy due to a known Windows ConPTY limitation, not a Vela bug

---

Built With

• Rust
• ratatui — Terminal UI framework
• ratatui-image + image — Image preview (Kitty/iTerm2/Sixel protocol detection, halfblock fallback)
• ssh2 — SFTP over SSH
• serde + toml — Configuration
• keyring — OS keychain password storage
• notify — Local filesystem auto-refresh

---

License

MIT — see LICENSE for details.