VVTerm

Your servers. Everywhere.

Overview

VVTerm is a cross-platform SSH terminal app for Apple platforms. The current codebase targets iOS and macOS, uses Ghostty for terminal rendering, libssh2/OpenSSL for SSH transport, CloudKit for sync, and Keychain for local credential storage.

Current State

• Main app target: VVTerm
• Companion target: VVTermLiveActivity
• Runtime targets: macOS 13.3+ and iOS 16.1+
• Hardware targets: Apple Silicon / arm64 only
• App-owned code is organized under VVTerm/App, VVTerm/Core, and VVTerm/Features
• The repo also contains tests, native vendor builds, feature specs under docs/specs, and the marketing site under web/

Implemented Feature Areas

Terminal and connections

• GPU-accelerated terminal rendering via GhosttyKit
• SSH authentication with password, SSH key, and SSH key + passphrase
• Connection modes for standard SSH, Tailscale, Mosh, and Cloudflare Access
• Multi-session connection management with tabs, split panes, reconnect handling, and persisted session state
• tmux-aware startup, attach, install, and recovery flows
• Rich paste and clipboard helpers for terminal input
• iOS keyboard accessory support, including special keys and custom actions
• iOS Live Activity status for active terminal connections

Servers and organization

• Workspaces with ordering, colors, and environment grouping
• Server metadata including favorites, tags, notes, last-connected timestamps, and biometric-unlock requirements
• Pro limit enforcement for workspaces, servers, tabs, and split panes
• Local-network SSH discovery via Bonjour and subnet probing

Remote files

• SFTP-backed remote file browser for iOS and macOS
• Directory browsing with breadcrumbs, sorting, hidden-file toggles, and persisted browser state
• File preview, upload, download, export/share, new folder, rename, move, and delete flows
• Permission editing and remote-file conflict resolution

Security and sync

• Keychain-backed storage for SSH credentials and Cloudflare service tokens
• CloudKit sync for servers, workspaces, terminal theme preferences, and terminal accessory profile data
• Full-app lock and per-server biometric unlock
• Privacy-mode support

Customization and productivity

• Built-in and custom terminal themes with validation, storage-path management, and sync-aware preference handling
• Customizable terminal accessory bar with reorderable actions and user-defined shortcuts
• Terminal presets for saved commands/snippets
• Settings surfaces for general, terminal, sync, keychain, pro, and about flows
• Welcome/onboarding and in-app support surfaces

Stats and voice input

• Remote server stats collection with live CPU and memory history
• On-device voice-to-command pipeline with MLX model management and Apple Speech fallback

Architecture

VVTerm uses a feature-first structure for app-owned code.

VVTerm/
├── App/                         # App entry, composition roots, shared root containers
├── Core/                        # Shared infrastructure and cross-feature primitives
│   ├── Logging/
│   ├── Network/
│   ├── Security/
│   ├── SSH/
│   ├── Sync/
│   ├── Terminal/
│   └── UI/
├── Features/                    # Product features
│   ├── ConnectionViews/
│   ├── LocalDiscovery/
│   ├── RemoteFiles/
│   ├── Security/
│   ├── Servers/
│   ├── Settings/
│   ├── Stats/
│   ├── Store/
│   ├── Support/
│   ├── TerminalAccessories/
│   ├── TerminalPresets/
│   ├── TerminalSessions/
│   ├── TerminalThemes/
│   ├── VoiceInput/
│   └── Welcome/
├── GhosttyTerminal/             # Ghostty bridge and terminal host views
├── Compatibility/               # Version/platform helpers
├── Generated/                   # Build-time generated sources
└── Resources/                   # Bundled assets, themes, terminfo, localizations

Feature modules follow these boundaries:

• Domain: pure types and rules
• Application: state, orchestration, coordinators, managers
• Infrastructure: persistence, transport, adapters, external integrations
• UI: SwiftUI/AppKit/UIKit presentation

Other top-level folders in the repo:

VVTerm-iOS/                     # iOS Info.plist and entitlements
VVTerm-macOS/                   # macOS Info.plist and entitlements
VVTermLiveActivity/             # ActivityKit target
VVTermShared/                   # Shared Activity attributes and small shared types
VVTermTests/                    # Unit and integration tests
VVTermUITests/                  # UI tests
Vendor/                         # Vendored native dependencies
docs/specs/                     # Feature specs and implementation notes
scripts/                        # Vendor build scripts
web/                            # Astro site for vvterm.com

Requirements

• Apple Silicon Mac for development
• Xcode 16.0+
• macOS 13.3+
• iOS 16.1+
• zig and cmake

Install the non-Xcode build tools with Homebrew:

brew install zig cmake

Building From Source

git clone https://github.com/vivy-company/vvterm.git
cd vvterm

# Build native vendor libraries (GhosttyKit + libssh2/OpenSSL)
./scripts/build.sh all

# Open the project in Xcode
open VVTerm.xcodeproj

./scripts/build.sh supports all, ghostty, ssh, clean, and help.

Dependencies

Native/vendor dependencies:

• libghostty for terminal emulation and rendering
• libssh2 for SSH transport
• OpenSSL for cryptography

Swift package dependencies currently resolved by the Xcode project:

• Cloudflared
• swift-mosh
• mlx-swift
• ZIPFoundation
• swift-numerics
• TweetNacl

Installation

Pro Tier

Feature	Free	Pro
Workspaces	1	Unlimited
Servers	3	Unlimited
Tabs	1	Unlimited
Split panes	No	Yes

Pricing: Monthly ($6.49), Yearly ($19.99), Lifetime ($29.99)

Documentation

• CONTRIBUTING.md for contribution workflow
• SECURITY.md for vulnerability reporting
• THIRD_PARTY_NOTICES.md for third-party notices
• CLA.md for the contributor license agreement
• docs/specs/ for feature specs such as biometric locks, local discovery, terminal themes, terminal accessories, remote rich clipboard, and the SFTP browser

License

VVTerm uses a dual-license model:

• Source code in this repository is licensed under GNU GPL v3.0 (LICENSE)
• Official App Store binaries are distributed under VVTerm's custom App Store EULA (LICENSE-APPSTORE.md, https://vvterm.com/terms)

If you obtain VVTerm from source and build it yourself, GPL-3.0 applies. If you obtain VVTerm via the App Store, App Store distribution terms apply to that binary.

Copyright © 2026 Vivy Technologies Co., Limited