mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-06-28 05:29:29 +00:00
38c5b2dc5f
- Add separator before About VibeTunnel menu item - Update README to use new banner image - Add high-resolution app icons and banner assets - Improve menu bar icon visibility
305 lines
No EOL
12 KiB
Markdown
305 lines
No EOL
12 KiB
Markdown
|
|
|
|
# VibeTunnel
|
|
|
|
VibeTunnel is a macOS application that bridges terminal applications to the web, enabling remote control of terminal tools from anywhere. It creates secure tunnels between local terminal sessions and web browsers, making it possible to access and control command-line applications like Claude Code remotely.
|
|
|
|
## Architecture Overview
|
|
|
|
VibeTunnel employs a multi-layered architecture designed for flexibility, security, and ease of use:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Web Browser (Client) │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ TypeScript/JavaScript Frontend │ │
|
|
│ │ - Asciinema Player for Terminal Rendering │ │
|
|
│ │ - WebSocket for Real-time Updates │ │
|
|
│ │ - Tailwind CSS for UI │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
↕ HTTPS/WebSocket
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ HTTP Server Layer │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ Dual Implementation: │ │
|
|
│ │ 1. Hummingbird Server (Swift) │ │
|
|
│ │ 2. Rust Server (tty-fwd binary) │ │
|
|
│ │ - REST APIs for session management │ │
|
|
│ │ - WebSocket streaming for terminal I/O │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
↕
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ macOS Application (Swift) │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ Core Components: │ │
|
|
│ │ - ServerManager: Orchestrates server lifecycle │ │
|
|
│ │ - SessionMonitor: Tracks active sessions │ │
|
|
│ │ - TTYForwardManager: Handles TTY forwarding │ │
|
|
│ │ - TerminalManager: Terminal operations │ │
|
|
│ │ - NgrokService: Optional tunnel exposure │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ UI Layer (SwiftUI): │ │
|
|
│ │ - MenuBarView: System menu bar integration │ │
|
|
│ │ - SettingsView: Configuration interface │ │
|
|
│ │ - ServerConsoleView: Diagnostics & logs │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### 1. **Native macOS Application**
|
|
|
|
The main application is built with Swift and SwiftUI, providing:
|
|
|
|
- **Menu Bar Integration**: Lives in the system menu bar with optional dock mode
|
|
- **Server Lifecycle Management**: Controls starting, stopping, and switching between server implementations
|
|
- **System Integration**: Launch at login, single instance enforcement, application mover
|
|
- **Auto-Updates**: Sparkle framework integration for seamless updates
|
|
|
|
Key files:
|
|
- `VibeTunnel/VibeTunnelApp.swift`: Main application entry point
|
|
- `VibeTunnel/Services/ServerManager.swift`: Orchestrates server operations
|
|
- `VibeTunnel/Models/TunnelSession.swift`: Core session model
|
|
|
|
### 2. **HTTP Server Layer**
|
|
|
|
VibeTunnel offers two server implementations that can be switched at runtime:
|
|
|
|
#### **Hummingbird Server (Swift)**
|
|
- Built-in Swift implementation using the Hummingbird framework
|
|
- Native integration with the macOS app
|
|
- RESTful APIs for session management
|
|
- File: `VibeTunnel/Services/HummingbirdServer.swift`
|
|
|
|
#### **Rust Server (tty-fwd)**
|
|
- External binary written in Rust for high-performance TTY forwarding
|
|
- Spawns and manages terminal processes
|
|
- Records sessions in asciinema format
|
|
- WebSocket streaming for real-time terminal I/O
|
|
- Source: `rust/tty-fwd/` directory
|
|
|
|
Both servers expose similar APIs:
|
|
- `POST /sessions`: Create new terminal session
|
|
- `GET /sessions`: List active sessions
|
|
- `GET /sessions/:id`: Get session details
|
|
- `POST /sessions/:id/send`: Send input to terminal
|
|
- `GET /sessions/:id/output`: Stream terminal output
|
|
- `DELETE /sessions/:id`: Terminate session
|
|
|
|
### 3. **Web Frontend**
|
|
|
|
A modern web interface for terminal interaction:
|
|
|
|
- **Terminal Rendering**: Uses asciinema player for accurate terminal display
|
|
- **Real-time Updates**: WebSocket connections for live terminal output
|
|
- **Responsive Design**: Tailwind CSS for mobile-friendly interface
|
|
- **Session Management**: Create, list, and control multiple terminal sessions
|
|
|
|
Key files:
|
|
- `web/`: Frontend source code
|
|
- `VibeTunnel/Resources/WebRoot/`: Bundled static assets
|
|
|
|
## Session Management Flow
|
|
|
|
1. **Session Creation**:
|
|
```
|
|
Client → POST /sessions → Server spawns terminal process → Returns session ID
|
|
```
|
|
|
|
2. **Command Execution**:
|
|
```
|
|
Client → POST /sessions/:id/send → Server writes to PTY → Process executes
|
|
```
|
|
|
|
3. **Output Streaming**:
|
|
```
|
|
Process → PTY output → Server captures → WebSocket/HTTP stream → Client renders
|
|
```
|
|
|
|
4. **Session Termination**:
|
|
```
|
|
Client → DELETE /sessions/:id → Server kills process → Cleanup resources
|
|
```
|
|
|
|
## Key Features
|
|
|
|
### Security & Tunneling
|
|
- **Ngrok Integration**: Optional secure tunnel exposure for remote access
|
|
- **Keychain Storage**: Secure storage of authentication tokens
|
|
- **Code Signing**: Full support for macOS code signing and notarization
|
|
|
|
### Terminal Capabilities
|
|
- **Full TTY Support**: Proper handling of terminal control sequences
|
|
- **Process Management**: Spawn, monitor, and control terminal processes
|
|
- **Session Recording**: Asciinema format recording for playback
|
|
- **Multiple Sessions**: Concurrent terminal session support
|
|
|
|
### Developer Experience
|
|
- **Hot Reload**: Development server with live updates
|
|
- **Comprehensive Logging**: Detailed logs for debugging
|
|
- **Error Handling**: Robust error handling throughout the stack
|
|
- **Swift 6 Concurrency**: Modern async/await patterns
|
|
|
|
## Technology Stack
|
|
|
|
### macOS Application
|
|
- **Language**: Swift 6.0
|
|
- **UI Framework**: SwiftUI
|
|
- **Minimum OS**: macOS 14.0 (Sonoma)
|
|
- **Architecture**: Universal Binary (Intel + Apple Silicon)
|
|
|
|
### Dependencies
|
|
- **Hummingbird**: HTTP server framework
|
|
- **Sparkle**: Auto-update framework
|
|
- **Swift Log**: Structured logging
|
|
- **Swift HTTP Types**: Type-safe HTTP handling
|
|
|
|
### Build Tools
|
|
- **Xcode**: Main IDE and build system
|
|
- **Swift Package Manager**: Dependency management
|
|
- **Cargo**: Rust toolchain for tty-fwd
|
|
- **npm**: Frontend build tooling
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
- macOS 14.0 or later
|
|
- Xcode 15.0 or later (for development)
|
|
- Rust toolchain (for building tty-fwd)
|
|
- Node.js and npm (for frontend development)
|
|
|
|
### Building from Source
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/amantus-ai/vibetunnel.git
|
|
cd vibetunnel
|
|
```
|
|
|
|
2. Build the Rust server:
|
|
```bash
|
|
cd rust/tty-fwd
|
|
cargo build --release
|
|
cd ../..
|
|
```
|
|
|
|
3. Build the web frontend:
|
|
```bash
|
|
cd web
|
|
npm install
|
|
npm run build
|
|
cd ..
|
|
```
|
|
|
|
4. Open in Xcode and build:
|
|
```bash
|
|
open VibeTunnel.xcodeproj
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Using the `vt` Command
|
|
|
|
VibeTunnel includes a command-line wrapper `vt` that forwards terminal application output through the tunnel. This allows remote monitoring and control of your terminal sessions. The command can be installed from the VibeTunnel settings or it can be found in `VibeTunnel.app/Contents/MacOS/Resources/vt` to symlink onto your `PATH`.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Run any command with VibeTunnel monitoring
|
|
vt [command] [args...]
|
|
|
|
# Examples
|
|
vt top # Monitor top command
|
|
vt python script.py # Run Python script with output forwarding
|
|
vt npm test # Run tests with VibeTunnel visibility
|
|
```
|
|
|
|
#### Claude Integration
|
|
```bash
|
|
vt --claude # Auto-locate and run Claude
|
|
vt --claude --help # Run Claude with --help option
|
|
vt --claude-yolo # Run Claude with --dangerously-skip-permissions
|
|
```
|
|
|
|
#### Shell Sessions
|
|
```bash
|
|
vt --shell # Launch current shell
|
|
vt -i # Launch current shell (short form)
|
|
```
|
|
|
|
#### Advanced Options
|
|
```bash
|
|
vt -S ls -la # Execute without shell wrapper (no alias resolution)
|
|
vt --no-shell-wrap cmd # Same as -S
|
|
vt --help # Show detailed help
|
|
```
|
|
|
|
The `vt` wrapper automatically uses shell resolution to handle aliases, functions, and built-ins, making it work seamlessly with your existing terminal setup.
|
|
|
|
### Getting Started
|
|
|
|
1. **Launch VibeTunnel**: The app appears in your menu bar
|
|
2. **Start Server**: Click the menu bar icon and select "Start Server"
|
|
3. **Access Web UI**: Navigate to `http://localhost:4020` (default port)
|
|
4. **Create Session**: Use the web interface to create new terminal sessions
|
|
5. **Remote Access**: Enable ngrok integration for secure remote access
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
```
|
|
vibetunnel/
|
|
├── VibeTunnel/ # macOS app source
|
|
│ ├── Services/ # Core services (servers, managers)
|
|
│ ├── Models/ # Data models
|
|
│ ├── Views/ # SwiftUI views
|
|
│ └── Resources/ # Assets and bundled files
|
|
├── rust/tty-fwd/ # Rust TTY forwarding server
|
|
├── web/ # TypeScript/JavaScript frontend
|
|
├── scripts/ # Build and utility scripts
|
|
└── Tests/ # Unit and integration tests
|
|
```
|
|
|
|
### Key Design Patterns
|
|
|
|
1. **Protocol-Oriented Design**: `ServerProtocol` allows swapping server implementations
|
|
2. **Actor Pattern**: Swift actors for thread-safe state management
|
|
3. **Dependency Injection**: Services are injected for testability
|
|
4. **MVVM Architecture**: Clear separation of views and business logic
|
|
|
|
### Testing
|
|
```bash
|
|
# Run Swift tests
|
|
swift test
|
|
|
|
# Run Rust tests
|
|
cd rust/tty-fwd && cargo test
|
|
|
|
# Run frontend tests
|
|
cd web && npm test
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
VibeTunnel is open source software licensed under the MIT License. See the LICENSE file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- Built with [Hummingbird](https://github.com/hummingbird-project/hummingbird) HTTP server framework
|
|
- Terminal rendering powered by [asciinema player](https://github.com/asciinema/asciinema-player)
|
|
- Auto-updates via [Sparkle](https://sparkle-project.org/)
|
|
|
|
---
|
|
|
|
*VibeTunnel - Bridging terminals to the web, one session at a time.* |