Skip to content

README.md

Latest commit

 

History

History
185 lines (131 loc) · 6.13 KB

README.md

File metadata and controls

185 lines (131 loc) · 6.13 KB
Raw

VShell

VShell is a desktop terminal workspace for local shells, SSH sessions, and SFTP file work. It is built with Tauri, Rust, React, TypeScript, xterm.js, and Bun.

The app is designed for people who want a compact terminal-first workflow: save local or SSH hosts, open terminals in tabs and split panes, browse remote files over SFTP, edit text files, preview media, and keep encrypted backups of host settings.

Features

  • Local shell and SSH host profiles
  • Terminal tabs with split pane layouts
  • SSH password auto sign-in when explicitly enabled
  • SFTP browser with upload, download, rename, move, copy, chmod, delete, and directory creation
  • Remote text editing with conflict checks
  • Remote media preview through Tauri's scoped asset protocol
  • Encrypted host storage and encrypted import/export backups
  • Windows startup integration, tray behavior, and update notifications
  • GitHub Releases based updater for public builds

Project Status

VShell is moving into public open-source development. The app builds, has automated checks, has a security policy, has an MIT license, and has a production webview CSP, but contributors should treat it as early production software while release signing and platform-specific installer testing mature.

Tech Stack

  • Tauri 2 for the native desktop shell
  • Rust for PTY, SSH/SFTP, encrypted storage, backups, startup registration, and updates
  • React 19 and TypeScript for the interface
  • Vite for frontend builds
  • Bun for JavaScript dependency management and scripts
  • Vitest for frontend unit tests

Prerequisites

Install these before running the app locally:

  • Bun
  • Rust
  • Tauri system dependencies for your OS

On Windows, install the Microsoft C++ Build Tools if Rust or Tauri asks for them. On Linux, install the WebKitGTK and system packages required by Tauri 2 for your distribution.

Getting Started

Clone the repository and install dependencies:

git clone https://github.com/xptea/VShell.git
cd VShell
bun install

Run the desktop app in development:

bun run tauri dev

Run only the web UI preview:

bun run dev

The browser preview is useful for UI work, but native features such as PTY sessions, SFTP, encrypted storage, dialogs, tray behavior, startup registration, and updates require the Tauri runtime.

Scripts

bun run dev
bun run build
bun run test
bun run tauri dev
bun run tauri build

Rust checks can be run directly:

cargo test --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo audit --file src-tauri/Cargo.lock

Dependency audits should also be clean before publishing:

bun audit
npm audit --audit-level=high

Production Build

Create a release build with:

bun run tauri build

Build outputs are generated under src-tauri/target/release/bundle/. Exact installer formats depend on the host OS and Tauri bundle target support.

See docs/RELEASE.md for the release checklist, signing notes, smoke tests, and updater asset names.

Auto Updates

The updater checks the public repository:

https://github.com/xptea/VShell

Version discovery works in this order:

  1. Read the root version file from the main branch.
  2. Fall back to the latest GitHub Release tag.

For update downloads to work, publish GitHub Release assets with these names:

vshell_<version>_x64-setup.exe
vshell_<version>_aarch64-setup.exe
vshell_<version>_x64-setup.dmg
vshell_<version>_x64.dmg
vshell_<version>_aarch64-setup.dmg
vshell_<version>_aarch64.dmg

The release tag may be either <version> or v<version>. For example, version 0.1.13 may use 0.1.13 or v0.1.13.

When cutting a release, keep these version values in sync:

  • package.json
  • package-lock.json
  • src-tauri/Cargo.toml
  • src-tauri/tauri.conf.json
  • root version
  • GitHub Release tag

Security Notes

  • Saved hosts are stored under the user's local app data directory.
  • Saved passwords are encrypted before storage. Windows uses DPAPI. macOS and Linux use the system keyring when available, with a local fallback key.
  • Backup exports are encrypted with a user-provided code.
  • SSH host keys are recorded and checked on later connections.
  • RSA SSH private-key support is disabled until the upstream Rust rsa advisory has a fixed release path. Prefer Ed25519 or ECDSA keys.
  • SFTP previews are exposed only through a scoped Tauri asset protocol path under the temporary VShell preview directory.
  • The Tauri webview uses a production CSP and only allows the scoped asset protocol for media previews.
  • The updater downloads installers from GitHub Releases and starts the platform installer. Release signing should be part of the public release process.

Please report security issues using the process in SECURITY.md. Use GitHub Issues for non-sensitive bugs only. The latest local audit notes are in docs/SECURITY_AUDIT.md.

Repository Layout

src/                  React and TypeScript UI
src/components/       App views and reusable UI components
src/lib/              Frontend helpers and Tauri command wrappers
src-tauri/src/        Rust commands, PTY, SSH/SFTP, storage, updater
src-tauri/icons/      Tauri app icons
docs/                 Release and security audit notes
.github/              Issue templates
tests/                Frontend unit tests
version               Latest public updater version

Contributing

Contributions are welcome. See CONTRIBUTING.md before opening an issue or pull request.

For project behavior expectations and support boundaries, see CODE_OF_CONDUCT.md and SUPPORT.md.

Recommended checks before opening a pull request:

bun run test
bun run build
cargo test --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo audit --file src-tauri/Cargo.lock

Keep changes focused, avoid committing generated build output, and update this README when behavior, setup, or release steps change.

License

VShell is licensed under the MIT License. See LICENSE for details.