# voltiusLocal

**Repository Path**: web/voltius-local

## Basic Information

- **Project Name**: voltiusLocal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Voltius-Local

> A modern multi-host management tool with SSH terminal, SFTP file transfer, port forwarding, Docker management, and more.
> This branch is a **local-only account version** — Cloud Account functionality has been removed, focusing entirely on local use cases.

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](./LICENSE)
[![Version](https://img.shields.io/badge/version-0.39.2-green.svg)](./package.json)
[![Tauri](https://img.shields.io/badge/Tauri-2.x-orange.svg)](https://tauri.app/)
[![React](https://img.shields.io/badge/React-19-blue.svg)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6.svg)](https://www.typescriptlang.org/)
[![Rust](https://img.shields.io/badge/Rust-1.x-dea584.svg)](https://www.rust-lang.org/)

---

## ✨ Features

### Core Features
- 🖥️ **SSH Terminal** - Built-in xterm.js with multi-tab, split pane, and session persistence
- 📂 **SFTP File Manager** - Dual-pane file browsing, upload/download, remote editing
- 🔌 **Port Forwarding** - Local/remote port forwarding with visual tunnel management
- 🐳 **Docker Integration** - Containers, images, volumes, and networks management
- 🌐 **Proxmox Integration** - VM/container management

### Account & Security
- 🔐 **Local Accounts** - Password-free (auto-generated key) or master password-protected
- 🔒 **Vault Locking** - Session lock/unlock with auto-lock timeout
- 🔑 **Key Management** - Built-in SSH key generation, import, and management
- 💾 **Local Encrypted Storage** - Credentials encrypted via OS keychain

### Cross-Platform
- 🪟 Windows
- 🐧 Linux
- 🍎 macOS
- 📱 Android

### Additional
- 🎨 Modern UI (glassmorphism design language)
- 🌍 Multi-language support
- 🔌 Plugin system
- 📋 Command palette (quick search/actions)

---

## 📦 System Requirements

### Desktop
| Dependency | Version | Notes |
|------------|---------|-------|
| Node.js | ≥ 18 | 20 LTS recommended |
| pnpm | ≥ 11 | Specified package manager |
| Rust | ≥ 1.70 | Tauri backend |
| Git | ≥ 2.30 | Optional, for cloning |

### Android Build (Optional)
| Dependency | Notes |
|------------|-------|
| Android SDK | compileSdk 34+ |
| Android NDK | r25+ |
| Rust targets | aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android, i686-linux-android |
| JDK | 17+ |

---

## 🚀 Quick Start

### 1. Clone the Repository

```bash
git clone https://gitee.com/web/voltius-local.git
cd voltius-local
```

### 2. Install Dependencies

```bash
pnpm install
```

### 3. Run in Development Mode

```bash
pnpm tauri dev
```

This starts both the Vite frontend dev server and the Tauri native window.

### 4. Build for Production

```bash
# Frontend build
pnpm build

# Tauri packaging
pnpm tauri build
```

Build artifacts are located in `src-tauri/target/release/bundle/`.

---

## 📱 Android Build

> For detailed Android development workflow, see [docs/android-dev.md](./docs/android-dev.md)

### Build with Docker (Recommended)

```bash
# Build aarch64 APK (for real devices)
docker build -t voltius-android -f Dockerfile.android .
docker run --rm -v $PWD:/project voltius-android bash -c \
  "cd /project && src-tauri/gen/android/gradlew :app:assembleDebug"

# Output path
# src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk
```

### Local Build

```bash
# Make sure Android SDK/NDK are installed and environment variables are set
# Windows example:
$env:ANDROID_HOME = "C:\Users\<you>\AppData\Local\Android\Sdk"
$env:ANDROID_NDK_HOME = "$env:ANDROID_HOME\ndk\<version>"

# Add all 4 Rust Android targets
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
```

### Full-Platform Release Build

`tauri android build` defaults to **release mode + all 4 architectures** (arm64-v8a / armeabi-v7a / x86 / x86_64). No extra flags needed.

```powershell
# Full-platform APK (all 4 architectures bundled, largest size, good for distribution)
pnpm tauri android build --apk

# Full-platform AAB (Google Play Store recommended format)
pnpm tauri android build --aab

# Split APKs per ABI (recommended — smaller size, install only what you need)
pnpm tauri android build --apk --split-per-abi

# Single-arch only (e.g., build only for your arm64 phone)
pnpm tauri android build --apk --target aarch64
```

**Output paths** (`src-tauri/gen/android/app/build/outputs/`):

```
├── apk/
│   ├── arm64/release/app-arm64-release.apk           ← arm64 real devices (recommended)
│   ├── arm/release/app-arm-release.apk               ← older armeabi-v7a devices
│   ├── x86_64/release/app-x86_64-release.apk         ← emulators
│   ├── x86/release/app-x86-release.apk               ← emulators
│   └── universal/release/app-universal-release.apk   ← all ABIs in one (largest)
└── aab/release/app-release.aab                       ← Google Play upload format
```

### R8 / ProGuard Notes (Required for Release)

Release builds enable R8 code shrinking and obfuscation (`isMinifyEnabled = true`). The following rules are **mandatory** — without them the app will **freeze at splash**, crash, or fail on encrypted storage:

| Rule File | Location | Purpose |
|-----------|----------|---------|
| `proguard-rules.pro` | `src-tauri/gen/android/app/` | In gen dir, loaded directly by Gradle |
| `proguard-voltius.pro` | `src-tauri/android/app/` | **Overlay dir** — survives `tauri android init` regenerations |

Four core keep rules (see `proguard-voltius.pro`):

```proguard
# JNI bridge classes — Rust loads them by string name; R8 obfuscation breaks reflection
-keep class com.voltius.app.VoltiusKeychain { *; }
-keep class com.voltius.app.VoltiusDownloads { *; }
-keep class com.voltius.app.TerminalKeyboard { *; }
-keep class com.voltius.app.MainActivity { *; }
```

Additionally, `androidx.security:security-crypto` (EncryptedSharedPreferences) depends on Google Tink, which references `javax.annotation.Nullable` / `GuardedBy` — removed from Android 13+ system classpath (targetSdk 33+):

```proguard
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.concurrent.GuardedBy
```

> If your release build gets stuck at "Starting Voltius..." — **99% chance the JNI keep rules are missing**. Debug builds don't obfuscate so they always work.

### Overlay Directory

`src-tauri/android/` is Tauri's config overlay. Running `tauri android init` to regenerate `gen/android/` will **never delete** this directory. Put custom files here to preserve them across regenerations:

```
src-tauri/android/
├── app/
│   ├── proguard-voltius.pro           ← custom ProGuard rules (already configured)
│   └── src/main/AndroidManifest.xml   ← custom Manifest permissions (already configured)
```

`gen/android/app/build.gradle.kts` is configured to scan both `gen/` and overlay directories for ProGuard rules.

### Reduce APK/AAB Size without changing functionality

The default is already a release build. Just target a single ABI + strip debug symbols to shrink the package drastically:

```powershell
# PowerShell: single-ABI, stripped symbols (works well for most arm64 phones)
$env:RUSTFLAGS = "-C strip=symbols"
$env:CARGO_PROFILE_RELEASE_STRIP = "symbols"
pnpm tauri android build --target aarch64 --aab

# For an APK instead of AAB:
# pnpm tauri android build --target aarch64 --apk

# Compare: debug build (larger, for development only)
pnpm tauri android build --debug --target aarch64 --apk
```

- Default release is much smaller than `--debug`; no need to add `--release`
- `--target aarch64`: builds only the target architecture to avoid oversized multi-ABI packages
- `--aab`: preferred Android distribution format for Play Store workflows
- `strip=symbols`: removes debug symbols without affecting app features at runtime

> For personal device testing, prefer `--target aarch64 --apk`. For distribution, prefer `--target aarch64 --aab`.

### Install on Device

```bash
# Release artifact (recommended)
adb install -r src-tauri/gen/android/app/build/outputs/apk/arm64/release/app-arm64-release.apk

# Debug artifact
adb install -r src-tauri/gen/android/app/build/outputs/apk/debug/app-debug.apk

# Launch
adb shell am start -n com.voltius.app/.MainActivity
```

---

## 🛠️ Common Commands

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start Vite frontend dev server |
| `pnpm tauri dev` | Start Tauri dev mode (with native window) |
| `pnpm build` | Production frontend build |
| `pnpm tauri build` | Full desktop packaging |
| `pnpm test` | Run unit tests |
| `pnpm tsc` | TypeScript type check |
| `pnpm tauri android dev` | Android development mode |
| `pnpm tauri android build` | Android APK/AAB build |

---

## 📂 Project Structure

```
voltius-local/
├── src/                     # Frontend source (React + TypeScript)
│   ├── components/          # UI components
│   ├── services/            # Business service layer
│   ├── stores/              # Zustand state management
│   ├── utils/               # Utility functions
│   ├── i18n/                # Internationalization resources
│   └── styles/              # Global styles
├── src-tauri/               # Tauri backend (Rust)
│   ├── src/
│   │   ├── commands/        # Tauri commands (frontend-callable)
│   │   ├── local/           # Local terminal functionality
│   │   ├── serial/          # Serial port functionality
│   │   ├── docker/          # Docker integration
│   │   └── ...
│   ├── tauri.conf.json     # Tauri configuration
│   └── Cargo.toml           # Rust dependencies
├── crates/                  # Shared Rust crates
│   ├── voltius-crypto/      # Cryptographic primitives
│   ├── voltius-crypto-wasm/ # WASM crypto version
│   └── voltius-diagnostics/ # Diagnostics utilities
├── scripts/                 # Build/utility scripts
├── docs/                    # Documentation
│   ├── local-only-account-plan.md   # Local account architecture
│   ├── android-dev.md               # Android dev workflow
│   ├── android-feature-gaps.md      # Android feature compatibility
│   └── design-surfaces.md           # UI design system
├── Dockerfile.android       # Android build image
├── package.json
├── Cargo.toml
└── LICENSE
```

---

## 🏗️ Account Architecture

This project removes Cloud Account functionality and retains only two local account modes:

| Mode | Description |
|------|-------------|
| `local-nopassword` | Password-free account with auto-generated 32-byte random key, ideal for personal single-device use |
| `local` | Master password-protected account. Password derives key via Argon2, supports vault locking |

### Removed Cloud Features
- ❌ Cloud Account registration/login
- ❌ Cloud sync (`push`/`pull`/realtime sync)
- ❌ Team/member management
- ❌ Subscription/Pro features
- ❌ Multi-vault Pro restriction

> Detailed modifications in [docs/local-only-account-plan.md](./docs/local-only-account-plan.md)

---

## 📝 Development Notes

### Tech Stack
- **Frontend**: React 19 + TypeScript + TailwindCSS 4
- **Backend**: Rust
- **Package Manager**: pnpm workspace
- **State Management**: Zustand
- **Terminal**: xterm.js
- **Build Tools**: Vite 8 + Tauri 2

### Design System
Voltius uses a unified **Surface design language** maintaining visual consistency through core tokens (ring, elevation, radius):
- `--t-ring` / `--t-ring-strong` - Edge outline
- `--t-elev-1/2/3` - Shadow elevation scale
- `--r-sm/md/lg` - Radius scale

See [docs/design-surfaces.md](./docs/design-surfaces.md)

### Important Notes
1. **Android TLS** - Android requires a preconfigured rustls TLS client (see `src-tauri/src/commands/http.rs::client_builder()`)
2. **Type Check** - Ensure `tsc --noEmit` passes before committing
3. **Signing Key** - `src-tauri/signing.key` is a private signing key — never commit to VCS
4. **Minimal Changes** - Prefer modifying existing files over creating new ones

---

## 🔌 Plugin Registry URL

Add the following plugin registry URL in the Voltius app to install community plugins:

```
https://gitee.com/web/voltius_sync_config/releases/download/main/plugins.json
```

---

## 🔗 Related Resources

- [Voltius Website](https://voltius.app/)
- [Tauri Documentation](https://tauri.app/v2/start/)
- [React Documentation](https://react.dev/)
- [Rust Documentation](https://www.rust-lang.org/learn)

---

## 🤝 Contributing

Issues and Pull Requests are welcome!

---

## 📄 License

This project is licensed under the [GNU Affero General Public License v3.0](./LICENSE).

---

## 📦 Third-Party Resources

- **Twemoji Country Flags** - CC BY 4.0 (see [NOTICE.md](./NOTICE.md))
- **Nerd Font Symbols** - MIT License (see [NOTICE.md](./NOTICE.md))