mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-03-30 10:16:10 +00:00
c6b000a421
🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
270 lines
No EOL
6.1 KiB
Markdown
270 lines
No EOL
6.1 KiB
Markdown
# VibeTunnel Linux
|
|
|
|
A Linux implementation of VibeTunnel that provides remote terminal access via web browser, fully compatible with the macOS VibeTunnel app.
|
|
|
|
## Features
|
|
|
|
- 🖥️ **Remote Terminal Access**: Access your Linux terminal from any web browser
|
|
- 🔒 **Secure**: Optional password protection and localhost-only mode
|
|
- 🌐 **Network Ready**: Support for both localhost and network access modes
|
|
- 🔌 **ngrok Integration**: Easy external access via ngrok tunnels
|
|
- 📱 **Mobile Friendly**: Responsive web interface works on phones and tablets
|
|
- 🎬 **Session Recording**: All sessions recorded in asciinema format
|
|
- ⚡ **Real-time**: Live terminal streaming with proper escape sequence handling
|
|
- 🛠️ **CLI Compatible**: Full command-line interface for session management
|
|
|
|
## Quick Start
|
|
|
|
### Build from Source
|
|
|
|
```bash
|
|
# Clone the repository (if not already done)
|
|
git clone <repository-url>
|
|
cd vibetunnel/linux
|
|
|
|
# Build web assets and binary
|
|
make web build
|
|
|
|
# Start the server
|
|
./build/vibetunnel --serve
|
|
```
|
|
|
|
### Using the Pre-built Binary
|
|
|
|
```bash
|
|
# Download latest release
|
|
wget <release-url>
|
|
chmod +x vibetunnel
|
|
|
|
# Start server on localhost:4020
|
|
./vibetunnel --serve
|
|
|
|
# Or with password protection
|
|
./vibetunnel --serve --password mypassword
|
|
|
|
# Or accessible from network
|
|
./vibetunnel --serve --network
|
|
```
|
|
|
|
## Installation
|
|
|
|
### System-wide Installation
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
### User Installation
|
|
|
|
```bash
|
|
make install-user
|
|
```
|
|
|
|
### As a Service (systemd)
|
|
|
|
```bash
|
|
make service-install
|
|
make service-enable
|
|
make service-start
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Server Mode
|
|
|
|
Start the web server to access terminals via browser:
|
|
|
|
```bash
|
|
# Basic server (localhost only)
|
|
vibetunnel --serve
|
|
|
|
# Server with password protection
|
|
vibetunnel --serve --password mypassword
|
|
|
|
# Server accessible from network
|
|
vibetunnel --serve --network
|
|
|
|
# Custom port
|
|
vibetunnel --serve --port 8080
|
|
|
|
# With ngrok tunnel
|
|
vibetunnel --serve --ngrok --ngrok-token YOUR_TOKEN
|
|
|
|
# Disable terminal spawning (detached sessions only)
|
|
vibetunnel --serve --no-spawn
|
|
```
|
|
|
|
Access the dashboard at `http://localhost:4020` (or your configured port).
|
|
|
|
### Session Management
|
|
|
|
Create and manage terminal sessions:
|
|
|
|
```bash
|
|
# List all sessions
|
|
vibetunnel --list-sessions
|
|
|
|
# Create a new session
|
|
vibetunnel bash
|
|
vibetunnel --session-name "dev" zsh
|
|
|
|
# Send input to a session
|
|
vibetunnel --session-name "dev" --send-text "ls -la\n"
|
|
vibetunnel --session-name "dev" --send-key "C-c"
|
|
|
|
# Kill a session
|
|
vibetunnel --session-name "dev" --kill
|
|
|
|
# Clean up exited sessions
|
|
vibetunnel --cleanup-exited
|
|
```
|
|
|
|
### Configuration
|
|
|
|
VibeTunnel supports configuration files for persistent settings:
|
|
|
|
```bash
|
|
# Show current configuration
|
|
vibetunnel config
|
|
|
|
# Use custom config file
|
|
vibetunnel --config ~/.config/vibetunnel.yaml --serve
|
|
```
|
|
|
|
Example configuration file (`~/.vibetunnel/config.yaml`):
|
|
|
|
```yaml
|
|
control_path: /home/user/.vibetunnel/control
|
|
server:
|
|
port: "4020"
|
|
access_mode: "localhost" # or "network"
|
|
static_path: ""
|
|
mode: "native"
|
|
security:
|
|
password_enabled: true
|
|
password: "mypassword"
|
|
ngrok:
|
|
enabled: false
|
|
auth_token: ""
|
|
advanced:
|
|
debug_mode: false
|
|
cleanup_startup: true
|
|
preferred_terminal: "auto"
|
|
update:
|
|
channel: "stable"
|
|
auto_check: true
|
|
```
|
|
|
|
## Command Line Options
|
|
|
|
### Server Options
|
|
- `--serve`: Start HTTP server mode
|
|
- `--port, -p`: Server port (default: 4020)
|
|
- `--localhost`: Bind to localhost only (127.0.0.1)
|
|
- `--network`: Bind to all interfaces (0.0.0.0)
|
|
- `--static-path`: Custom path for web UI files
|
|
|
|
### Security Options
|
|
- `--password`: Dashboard password for Basic Auth
|
|
- `--password-enabled`: Enable password protection
|
|
|
|
### ngrok Integration
|
|
- `--ngrok`: Enable ngrok tunnel
|
|
- `--ngrok-token`: ngrok authentication token
|
|
|
|
### Session Management
|
|
- `--list-sessions`: List all sessions
|
|
- `--session-name`: Specify session name
|
|
- `--send-key`: Send key sequence to session
|
|
- `--send-text`: Send text to session
|
|
- `--signal`: Send signal to session
|
|
- `--stop`: Stop session (SIGTERM)
|
|
- `--kill`: Kill session (SIGKILL)
|
|
- `--cleanup-exited`: Clean up exited sessions
|
|
|
|
### Advanced Options
|
|
- `--debug`: Enable debug mode
|
|
- `--cleanup-startup`: Clean up sessions on startup
|
|
- `--server-mode`: Server mode (native, rust)
|
|
- `--no-spawn`: Disable terminal spawning (creates detached sessions only)
|
|
- `--control-path`: Control directory path
|
|
- `--config, -c`: Configuration file path
|
|
|
|
## Web Interface
|
|
|
|
The web interface provides:
|
|
|
|
- **Dashboard**: Overview of all terminal sessions
|
|
- **Terminal View**: Real-time terminal interaction
|
|
- **Session Management**: Start, stop, and manage sessions
|
|
- **File Browser**: Browse filesystem (if enabled)
|
|
- **Session Recording**: Playback of recorded sessions
|
|
|
|
## Compatibility
|
|
|
|
VibeTunnel Linux is designed to be 100% compatible with the macOS VibeTunnel app:
|
|
|
|
- **Same API**: Identical REST API and WebSocket endpoints
|
|
- **Same Web UI**: Uses the exact same web interface
|
|
- **Same Session Format**: Compatible asciinema recording format
|
|
- **Same Configuration**: Similar configuration options and structure
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.21 or later
|
|
- Node.js and npm (for web UI)
|
|
- Make
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Install dependencies
|
|
make deps
|
|
|
|
# Build web assets
|
|
make web
|
|
|
|
# Build binary
|
|
make build
|
|
|
|
# Run in development mode
|
|
make dev
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Format and lint code
|
|
make check
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
linux/
|
|
├── cmd/vibetunnel/ # Main application
|
|
├── pkg/
|
|
│ ├── api/ # HTTP server and API endpoints
|
|
│ ├── config/ # Configuration management
|
|
│ ├── protocol/ # Asciinema protocol implementation
|
|
│ └── session/ # Terminal session management
|
|
├── scripts/ # Build and utility scripts
|
|
├── Makefile # Build system
|
|
└── README.md # This file
|
|
```
|
|
|
|
## License
|
|
|
|
This project is part of the VibeTunnel ecosystem. See the main repository for license information.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see the main VibeTunnel repository for contribution guidelines.
|
|
|
|
## Support
|
|
|
|
For support and questions:
|
|
1. Check the [main VibeTunnel documentation](../README.md)
|
|
2. Open an issue in the main repository
|
|
3. Check existing issues for known problems |