The ultimate bridge for your agent in remote environments.
Agent Tunnel allows your local instance of Gemini CLI, Claude Code, or any other agent to work transparently on any remote Linux server, router (OpenWrt/Entware), or Mac via SSH. Forget about manual file uploads or constant context switching: with Agent Tunnel, your local machine and the remote server become one.
- 🔄 Real-time Sync: Native integration with Mutagen for ultra-fast bi-directional synchronization.
- ⚡ Command Interception: Execute commands like
npm install,ls, ormkdirdirectly on the remote host from your local terminal. - 🌐 Intuitive Web UI: Configure your sessions, manage credentials, and monitor real-time logs at
http://localhost:3456. - 🔑 Automatic Key Management: Automatic generation and injection of SSH keys for a frictionless connection.
- 🛠️ Direct Mode (SSH-Only): If the remote device doesn't support Mutagen (e.g., older architectures), Agent Tunnel automatically activates direct execution mode.
- Node.js: >= 22.12.0
- Astro: ^6.1.1 (For Frontend development)
- SSH2: ^1.17.0 (SSH client for Node.js)
- Mutagen: Required for real-time file synchronization.
- SSH Client: Installed on the system.
- SSH Server: Compatible with public key authentication.
- SFTP Server: (Optional) Recommended for Mutagen synchronization.
- Start the Bridge:
./start-bridge.sh
- Configure your Session:
Open
http://localhost:3456in your browser. - Connect: Enter your remote host details, map your local folder, and click Activate Sync.
- Work: Use Gemini CLI (or your preferred agent) in your local folder. All commands and file changes will be automatically reflected on the remote host.
Agent Tunnel injects smart files into your working directory to facilitate integration:
activate.sh: Sets up environment variables for the active session.GEMINI.md: Provides direct instructions to the AI for using the tunnel.remote-exec.sh: The engine that wraps and sends your commands to the remote server.
If automatic injection fails, authorize the key manually from your local terminal:
ssh-copy-id -i ~/.ssh/id_rsa_bridge.pub [user]@[remote-ip]If Mutagen fails to copy the agent or cannot find the SFTP server:
On OpenWrt:
opkg update && opkg install openssh-sftp-serverOn Entware (ASUS, Padavan, etc.):
opkg update && opkg install sftp-serverEnsure the .ssh directory has the correct permissions:
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keysTo connect to a remote Mac, enable Remote Login in System Settings > General > Sharing.
- All configurations are stored locally in
~/.gemini-bridge/configs/. - Credentials never leave your local environment.
- SSH keys are managed with standard Unix permissions (600/700).
Developed with ❤️ by JaimeGH and Gemini.
El puente definitivo para tu agente en entornos remotos.
Agent Tunnel permite que tu instancia local de Gemini CLI o Claude Code o lo que sea trabaje de forma transparente en cualquier servidor Linux remoto, router (OpenWrt/Entware) o Mac a través de SSH. Olvida las subidas manuales de archivos o el cambio constante de contexto: con Agent Tunnel, tu máquina local y el servidor remoto se convierten en uno solo.
- 🔄 Sincronización en Tiempo Real: Integración nativa con Mutagen para una sincronización bidireccional ultrarrápida.
- ⚡ Intercepción de Comandos: Ejecuta comandos como
npm install,lsomkdirdirectamente en el remoto desde tu terminal local. - 🌐 Web UI Intuitiva: Configura tus sesiones, gestiona credenciales y monitoriza logs en tiempo real desde
http://localhost:3456. - 🔑 Gestión Automática de Llaves: Generación e inyección automática de llaves SSH para una conexión sin fricción.
- 🛠️ Modo Directo (SSH-Only): Si el dispositivo remoto no soporta Mutagen (ej. arquitecturas antiguas), Agent Tunnel activa automáticamente el modo de ejecución directa.
- Node.js: >= 22.12.0
- Astro: ^6.1.1 (Para el desarrollo del Frontend)
- SSH2: ^1.17.0 (Cliente SSH para Node.js)
- Mutagen: Requerido para la sincronización de archivos en tiempo real.
- SSH Client: Instalado en el sistema.
- Servidor SSH: Compatible con autenticación por llave pública.
- SFTP Server: (Opcional) Recomendado para la sincronización con Mutagen.
- Inicia el Bridge:
./start-bridge.sh
- Configura tu Sesión:
Abre
http://localhost:3456en tu navegador. - Conecta: Introduce los datos de tu host remoto, mapea tu carpeta local y haz clic en Activate Sync.
- Trabaja: Usa Gemini CLI en tu carpeta local. Todos los comandos y cambios de archivos se reflejarán automáticamente en el remoto.
Agent Tunnel inyecta archivos inteligentes en tu directorio de trabajo para facilitar la integración:
activate.sh: Configura las variables de entorno para la sesión activa.GEMINI.md: Proporciona instrucciones directas a la IA para el uso del túnel.remote-exec.sh: El motor que envuelve y envía tus comandos al servidor remoto.
Si la inyección automática falla, autoriza la llave manualmente desde tu terminal local:
ssh-copy-id -i ~/.ssh/id_rsa_bridge.pub [usuario]@[ip-remota]Si Mutagen falla al copiar el agente o no encuentra el servidor SFTP:
En OpenWrt:
opkg update && opkg install openssh-sftp-serverEn Entware (ASUS, Padavan, etc.):
opkg update && opkg install sftp-serverAsegúrate de que el directorio .ssh tenga los permisos correctos:
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keysPara conectar con un Mac remoto, activa Sesión remota en Ajustes del Sistema > General > Compartir.
- Todas las configuraciones se almacenan localmente en
~/.gemini-bridge/configs/. - Las credenciales nunca salen de tu entorno local.
- Las llaves SSH se gestionan con permisos estándar de Unix (600/700).
Developed with ❤️ by JaimeGH and Gemini.