fileterm

---

Download the Official Release

Download the latest release from GitHub Releases:

For step-by-step instructions, see the English Installation Guide or 简体中文安装指南.

• macOS: packages for Apple Silicon (arm64) and Intel (x64).
• Windows: x64 and ARM64 NSIS installers and portable .exe files; installed builds download, verify, and install architecture-matched updates after restart.
• Linux: x86_64 and arm64 .deb, .rpm, and .AppImage packages, plus Pacman .pkg.tar.zst packages for Arch x86_64 and Arch Linux ARM aarch64.

Linux packages

Every Linux package includes the FileTerm launcher, application icons, AppStream metadata, and the MIT license. The .deb, .rpm, and Pacman packages declare runtime dependencies for the system package manager to install; the RPM package requires a distribution that provides WebKitGTK 4.1 and OpenSSL 3. AppImage runs without installation, bundles its runtime libraries, and includes a .zsync sidecar for differential updates with AppImageUpdate. It still requires a host glibc compatible with the Ubuntu 22.04 build baseline.

Format	Architectures and supported systems	Install or run
.AppImage	x86_64, arm64; major Linux desktop distributions with AppImage support	chmod +x FileTerm-*-linux-<arch>.AppImage && ./FileTerm-*-linux-<arch>.AppImage
.deb	x86_64, arm64; Debian, Ubuntu, and derivatives	sudo apt install ./FileTerm-<version>-linux-<arch>.deb
.rpm	x86_64, arm64; Fedora, openSUSE, and RPM distributions with WebKitGTK 4.1 and OpenSSL 3	Fedora: sudo dnf install ./FileTerm-<version>-linux-<arch>.rpm; openSUSE: sudo zypper install ./FileTerm-<version>-linux-<arch>.rpm
.pkg.tar.zst	x86_64; Arch Linux, Manjaro, EndeavourOS, and Arch derivatives; aarch64; Arch Linux ARM	sudo pacman -U ./FileTerm-<version>-linux-<arch>.pkg.tar.zst

The official Arch Linux distribution supports x86_64. The ARM64 package targets the separate Arch Linux ARM distribution and cannot be installed on x86_64. Select the matching linux-x86_64 or linux-arm64 release asset. If an AppImage does not start when double-clicked, run chmod +x on the downloaded architecture-matched file and launch it from a terminal.

On first launch, FileTerm uses Chinese for Chinese system locales and English for all other locales. You can change the language in Settings; a saved choice takes precedence on later launches.

Windows, macOS, and supported Linux AppImage/DEB/RPM builds use signed in-app updates. AppImages must be in a writable directory; DEB/RPM installation may require administrator authorization. Pacman packages and unsupported installations open the matching GitHub Release page. See the installation guides for first-run requirements and older AppImage EGL workarounds.

Want to run from source or contribute? Continue to Getting Started from Source.

What Is FileTerm?

FileTerm is built for daily remote work by developers and operations teams. It brings remote terminals, file management, transfer tasks, and connection profiles into one desktop workspace.

• SSH sessions pair terminal work naturally with SFTP file panels.
• FTP/FTPS sessions use a focused file-only workflow.
• Multiple connections run side by side in tabs without interrupting each other.
• Uploads, downloads, progress, and errors are managed in one transfer center.
• Connection profiles, workspace state, and themes are designed for long-term daily use.

The official release focuses on the most frequent SSH / SFTP / FTP / FTPS workflows: reliable remote terminals, file operations, and transfers.

Core Capabilities

Capability	Description
SSH profile management	Create, edit, delete, and group SSH profiles with JSON persistence.
FTP/FTPS profile management	Uses a connection model kept separate from SSH and supports secure FTP transfers.
SSH terminal	Powered by xterm.js with input/output, resize, search, clipboard support, and a floating command bar.
SFTP file management	Browse remote directories; read, write, create, delete, rename, and change permissions.
FTP/FTPS file management	FTP/FTPS sessions with remote browsing, file operations, and resumable transfers.
File editor	A Monaco Editor-based two-pane file tree and editor with syntax highlighting, find/replace, encoding, and language controls.
Terminal directory sync	Keeps the active SSH working directory and file manager in sync.
Root privilege sync	Detects sudo / su in the terminal and synchronizes the file-manager permission context.
Virtualized file list	Uses virtual scrolling for efficient browsing of large remote directories.
Transfer center	Centralized uploads, downloads, resume support, progress, speed, cancellation, and recursive folder transfers.
Workspace tabs	Parallel connections, disconnect/reconnect, persisted state, and animated tab transitions.
Command templates	Grouped quick commands, parameter placeholders, and one-click sending.
Theme system	Dark and light themes through tokens, CSS variables, and component skins.
Remote status monitoring	Connection status and system-resource summaries.
Theme and desktop shell	Dark and light themes, sidebars, file drawer, focus mode, and dedicated management windows.

Technology Stack

Desktop	Renderer	Language	Terminal	Editor	Protocols	Tooling
Tauri v2	React + Vite	Rust + TypeScript	xterm.js	Monaco Editor	russh/russh-sftp + suppaftp + tokio-*	Cargo + npm workspaces

renderer UI    -> React workspace, tabs, files, terminal
Tauri bridge   -> typed Rust command/event boundary
Rust services  -> session lifecycle, storage, update and protocol services
protocols      -> russh SSH/SFTP, FTP/FTPS, Telnet and Serial adapters
theme system   -> tokens -> vars -> skins -> terminal colors

Architecture Principles

Renderer UI
  -> Application State
    -> Tauri API bridge
      -> Rust commands/events
        -> Desktop services
          -> Session workers
            -> Protocol clients

• packages/core is the single source of truth for domain models.
• The renderer never accesses SSH, SFTP, or FTP/FTPS protocol clients directly.
• All system capabilities are exposed through Rust commands/events -> tauri-api.ts -> renderer.
• SSH/SFTP and FTP/FTPS remain separate at controller and protocol layers.
• Transfer progress enters one transfer system instead of being maintained separately by components.

See docs/architecture.md for the complete architecture map.

Getting Started from Source

Requirements

• Node.js >= 22.12.0
• npm
• Rust stable, plus the Tauri system dependencies for your platform

On Linux (Ubuntu/Debian) you also need the GTK and WebKit runtimes:

# Ubuntu 24.04 and newer
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev patchelf build-essential libssl-dev

# On Ubuntu 22.04, replace 4.1 with 4.0

npm run dev requires a local graphical session. GTK cannot initialize over plain SSH, on a headless server, or in a Wayland session without XWayland. In those cases the launcher prints the current display environment and troubleshooting hints instead of a bare GTK panic.

Install and Run

npm install
npm run dev

dev, build, and typecheck build @fileterm/core, @fileterm/shared, and @fileterm/storage first, since their entry points resolve to dist/. No manual build step is needed after a fresh clone.

Common Commands

npm run dev
npm run test
npm run typecheck
npm run build
npm run release:mac
npm run release:win
npm run release:linux

Releases and Updates

• A vX.Y.Z tag on a release/* commit runs the Tauri-only Release Action and publishes macOS arm64/x64 DMGs and signed updater archives, Windows x64/arm64 NSIS installers and portable executables, and Linux x86_64/arm64 .deb, .rpm, and .AppImage packages plus Arch x86_64/Arch Linux ARM aarch64 .pkg.tar.zst packages.
• The release jobs publish signed Windows installers/portable executables, macOS updater archives, and Linux AppImage/DEB/RPM payloads with .sig files. A combined latest.json contains architecture- and format-specific entries; clients verify the matching package before updating. Linux payloads are signed after final repacking, including AppImage removal of display libraries that must match the host's Mesa/EGL stack.
• Configure the repository Actions Secret TAURI_SIGNING_PRIVATE_KEY with the Tauri updater private-key contents. Never commit that private key.
• macOS release bundles use ad-hoc signing without an Apple Developer certificate or notarization. The in-app updater verifies signed .app.tar.gz archives, backs up the old app before installation, and restarts after saving transfer checkpoints. Install the app in a writable Applications folder; first launch or a blocked update may require Open Anyway in Privacy & Security. Existing versions without the macOS updater need one manual DMG installation first.

Repository Layout

fileterm/
  apps/
    tauri/                   # Tauri + Rust desktop app
      src/
        bridge/              # typed Tauri command/event API
        renderer/            # React workspace UI
      src-tauri/             # Rust commands, services, sessions, and bundling
  packages/
    core/                    # domain types
    storage/                 # repository abstractions
    shared/                  # shared constants and utilities
  docs/
    architecture.md          # architecture map
    roadmap.md               # product roadmap
    plans/                   # active and completed execution plans
    decisions/               # architecture decisions
    quality/                 # quality and release checks
  AGENTS.md                  # map for human and AI collaborators

Roadmap

Post-release priorities:

1. Keep improving the stability and usability of the SSH / SFTP / FTP / FTPS core workflows.
2. Keep refining the Tauri workspace, session service, and renderer boundaries.
3. Continue consolidating domain types in packages/core.
4. Improve transfer tasks, errors, themes, terminal input, file drawers, and the desktop shell.
5. Maintain release quality and distribution for macOS, Windows, and Linux.

See docs/roadmap.md for the full plan.

Open Source Components

• xterm.js for SSH terminal rendering, input/output, and resize handling.
• Monaco Editor for file editing, syntax highlighting, and search/replace.
• Bundled fonts and icon fonts: see THIRD_PARTY_NOTICES.md for their licenses and sources.

Contributing

This repository treats the codebase as its record system:

• AGENTS.md is the entry map for collaboration.
• docs/architecture.md records stable architecture facts.
• docs/plans/active contains active cross-layer plans.
• docs/decisions records confirmed architecture decisions.
• .agents/extensions contains feature drafts and extension designs.

For a substantial feature, please add or update an active plan before writing code.

Contributors

Thank you to everyone who makes FileTerm better.

Community

Scan the QR code to join the FileTerm WeChat community for usage discussions, feedback, and product updates.

You can also join the QQ group: 534418986.

Support the Project

If FileTerm helps you, please consider starring the project on GitHub:

License

FileTerm source code is open-sourced under the MIT License. Bundled fonts and icon fonts remain under their respective licenses; see THIRD_PARTY_NOTICES.md.