porterminal v1.0.5

Entrega una computadora a un agente, con control total, y obsérvalo.
Un comando, una URL. (También una terminal elegante para tu propio teléfono).

1. uvx ptn
2. Entrega la URL a un agente de IA, o escanea el código QR tú mismo
3. Obsérvalo trabajar en cualquier navegador y toma el control cuando quieras

[!WARNING] Esa URL completa es acceso total a esta computadora. Contiene un código de acceso aleatorio por cada inicio, y cualquiera (o cualquier agente de IA) a quien se la entregues obtiene un shell real en tu máquina. Trata la URL y el código QR como un secreto, compártelos solo con personas y agentes de confianza, y lee Seguridad antes de apuntar Porterminal a algo importante.

Por qué

Necesitaba algo peligrosamente fácil para acceder de forma remota a una computadora.

ngrok requiere registro y el plan gratuito apesta. Cloudflare Tunnel es una excelente infraestructura, pero por sí solo solo te da un túnel, no una terminal apta para el teléfono. Tailscale es genial cuando controlas ambos extremos, pero aun así implica unir dispositivos a una red privada. Termius requiere una configuración complicada: reenvío de puertos, reglas de firewall, gestión de claves...

Así que construí algo más simple: ejecuta un comando, escanea un código QR, empieza a escribir.

Entonces me di cuenta: el mismo truco (un comando, una URL) es la forma más fácil de darle a un agente de IA una terminal real en cualquier computadora. Ni servidor MCP que escribir, ni claves SSH, ni Docker, ni configuración. Ejecuta uvx ptn, entrega la URL, y el agente ejecuta comandos, lee la pantalla y responde a las indicaciones en esa máquina. Y como es una terminal web, puedes abrir la misma sesión en cualquier navegador para verla trabajar en vivo, o tomar el teclado y asumir el control.

Características

• Entrega una computadora a un agente, con control total, y obsérvalo - Dale a un agente de IA la URL y obtendrá una terminal real en la máquina vía MCP o REST simple. Abre la misma sesión en cualquier navegador para verla trabajar en vivo y toma el teclado cuando quieras. Sin claves, sin Docker. El agente aprende cómo hacerlo desde <url>/llms.txt y <url>/.well-known/mcp.json. Consulta Acceso de agentes.
• Un comando, acceso instantáneo - uvx ptn y tú (o un agente) obtienen una terminal real en esta máquina. Sin SSH, sin reenvío de puertos, sin archivos de configuración. Túnel de Cloudflare + código QR.
• Realmente utilizable en el móvil - Optimizada para pantalla táctil con desplazamiento con inercia, zoom con pellizco, gestos de deslizamiento y teclas modificadoras (Ctrl, Alt).
• Aplicaciones de terminal completas - vim, htop, less, tmux funcionan correctamente con el manejo adecuado del búfer de pantalla alternativa.
• Sesiones persistentes de varias pestañas - Las sesiones sobreviven a las desconexiones. Cierra el navegador, cambia de red, reconéctate desde otro dispositivo, y tu shell y tus procesos en ejecución seguirán allí. Tú y un agente pueden compartir una sesión: obsérvala trabajar o toma el control.
• Multiplataforma - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell y cualquier shell vía $SHELL). Detecta automáticamente tus shells.
• Difícil de adivinar por defecto - Cada inicio añade una ruta de acceso aleatoria independiente de 128 bits. El nombre de host del túnel desnudo y cualquier ruta incorrecta devuelven 404. La URL está oculta en la pantalla, pero el código QR contiene la credencial completa, así que mantén ambos en privado. Pulsa c para copiar las instrucciones del agente y la URL, o u para copiar solo la URL.

Instalación

Instalación en una línea (uv + ptn):

Requiere Python 3.12+ y cloudflared (se instala automáticamente si falta).

Uso

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

Mientras se ejecuta: con un túnel activo, la URL de conexión está oculta en la pantalla por privacidad. Pulsa c para copiar las instrucciones del agente y la URL, incluidos /mcp, /api/agent/run y /llms.txt; pulsa u para copiar solo la URL; o escanea el código QR para conectarte. Ctrl+C detiene el servidor.

Acceso de agentes (MCP + REST)

La misma URL también funciona para agentes de IA. Los clientes compatibles con MCP pueden usar <url>/mcp (Streamable HTTP) para herramientas nativas tipadas. Los agentes que no pueden registrar un servidor MCP pueden usar la alternativa REST en <url>/api/agent/run con solicitudes HTTP normales. Cualquiera de las dos rutas crea un shell de agente persistente, mostrado como una pestaña 🤖 que puedes observar y desde tu teléfono tomar el control.

Entrega al agente la URL generada completa, incluido su código de acceso. Los clientes MCP pueden auto-descubrir el servidor desde <url>/.well-known/mcp.json (el descriptor server.json de MCP), y hay un <url>/llms.txt legible por humanos y agentes con instrucciones de uso. La página base también incluye pistas visibles para la accesibilidad de los agentes que controlan el navegador, mientras que la interfaz humana se mantiene compacta. Ejemplo de configuración de cliente:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

Herramientas MCP: run_command (salida limpia + código de salida), read_screen, send_keys, send_signal (Ctrl-C / EOF).

Alternativa REST:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

La respuesta incluye un session_id; reutilízalo con <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal y DELETE <url>/api/agent/session.

Cuando abres Porterminal en tu teléfono, el botón de copiar de la parte superior derecha copia el mismo texto de uso compartido listo para agentes. Los agentes que solo usan el navegador también tienen una alternativa en la página base: un espejo de Pantalla de terminal legible por DOM y una Entrada de terminal claramente etiquetada.

Seguridad: <url> significa la URL generada completa, incluido su código de acceso aleatorio. El nombre de host del túnel desnudo no expone nada, pero cualquiera (o cualquier agente) con la URL completa obtiene acceso completo a un shell sin privilegios elevados. Consulta docs/agent-access.md.

Gestos en el móvil

Teclas modificadoras (Ctrl, Alt, Shift): toca una vez para modo sostenido (una pulsación), dos toques para fijarlo.

Modo de composición (botón ▤): alterna un campo de entrada de texto donde puedes escribir o dictar, editar tu texto con todas las funciones de edición móvil (autocorrección, sugerencias, posicionamiento del cursor) y luego enviarlo a la terminal. Útil para comandos más largos o entrada por voz.

Configuración

Ejecuta ptn --init para crear una configuración inicial. Detecta automáticamente los scripts del proyecto desde package.json, pyproject.toml o Makefile y los añade como botones:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

O crea ptn.yaml manualmente:

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

La configuración se busca en este orden: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Seguridad

Cada inicio crea una nueva ruta aleatoria de 128 bits, como https://<tunnel>.trycloudflare.com/<access-code>/. Todas las rutas de navegador, WebSocket, MCP, REST, salud y estáticas requieren ese prefijo exacto; el host desnudo y las rutas incorrectas devuelven 404. Esto hace que forzar por fuerza bruta un nombre de host de túnel descubierto sea poco práctico.

La URL generada completa sigue siendo una credencial de portador: cualquiera que la obtenga tiene acceso al shell. Reinicia Porterminal para rotar el código si se filtra. La contraseña opcional añade autenticación a los WebSockets del navegador, pero MCP y REST siguen confiando en la URL completa para que los agentes puedan usar el flujo de un solo enlace.

Un navegador recuerda una contraseña correcta en almacenamiento de texto plano limitado a esa URL de inicio completa. Guardar una contraseña para un inicio más reciente en el mismo origen retira las entradas de contraseña más antiguas de Porterminal; borrar o rechazar una contraseña recordada las elimina todas sin tocar el resto del almacenamiento del navegador. En consecuencia, los inicios simultáneos en el mismo origen pueden volver a solicitar la contraseña, mientras que una conexión ya autenticada permanece conectada.

Desde la interfaz: abre Ajustes (icono de engranaje) y usa la sección Seguridad para establecer/cambiar la contraseña y alternar el requisito de contraseña. Los cambios requieren reiniciar el servidor.

Desde la CLI:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

Consulta docs/security.md para más detalles.

Solución de problemas

¿Falla la conexión? Usa la URL generada completa, incluido su código de acceso. Los problemas del túnel de Cloudflare también pueden resolverse reiniciando el servidor (Ctrl+C, luego ptn) para obtener un túnel y una ruta de acceso nuevos.

¿uvx ptn sigue ejecutando una versión anterior? Una instalación existente de uv tool puede tener prioridad. Ejecuta uv tool upgrade ptn, o evita las herramientas instaladas con uvx --isolated ptn@latest.

¿No se detecta el shell? Establece tu variable de entorno $SHELL o configura los shells en ptn.yaml.

Contribuciones

Este proyecto no acepta contribuciones externas (pull requests o cambios de código) por razones de seguridad (consulta CONTRIBUTING.md). Eres libre de hacer un fork y ejecutar tu propia copia bajo AGPL-3.0.

Ejecutar desde el código fuente:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

Licencia

AGPL-3.0