porterminal

<p align="center">
  <a href="https://github.com/porterminal/porterminal">
    <img src="https://raw.githubusercontent.com/porterminal/porterminal/master/assets/header.png?v=9" alt="PTN — Terminal portátil con ilustración QR decorativa." width="800">
  </a>
</p>

<h1 align="center">Dale a tu agente cualquier computadora</h1>

<p align="center">
  Un comando. Una URL. Un terminal real para tu agente, una vista en vivo para ti.
</p>

<p align="center">
  <a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/v/ptn?style=flat-square&amp;logo=pypi&amp;logoColor=white&amp;label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/pyversions/ptn?style=flat-square&amp;logo=python&amp;logoColor=white" alt="Python"></a>
  <a href="https://github.com/porterminal/porterminal/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/porterminal/porterminal/ci.yml?branch=master&amp;style=flat-square&amp;logo=github&amp;label=CI" alt="CI"></a>
  <a href="https://github.com/porterminal/porterminal/blob/master/LICENSE"><img src="https://img.shields.io/github/license/porterminal/porterminal?style=flat-square" alt="License"></a>
</p>

Ejecuta Porterminal en una computadora con Windows, macOS o Linux y entrega el
enlace generado a tu agente de IA. Obtiene un shell real con los archivos, herramientas y proyectos
de esa máquina. Abre el mismo enlace en tu teléfono o en cualquier navegador para observar
al agente trabajar y escribir en su terminal.

## Empieza aquí

En la computadora que quieres darle a tu agente:

```bash
uvx ptn
```

1. **Dale el enlace al agente.** Pulsa **`c`** en la ventana local de Porterminal
   para copiar la URL y las instrucciones de conexión. Pégalas en tu agente
   junto con una tarea. El agente necesita compatibilidad con MCP remoto o una forma de hacer solicitudes HTTP.
2. **Abre tu vista.** Escanea el código QR o abre la URL completa en un navegador.
   Selecciona la **pestaña 🤖** del agente para ver su terminal.
3. **Trabajen juntos.** Observa la salida, responde a un prompt interactivo, escribe un
   comando o cierra la pestaña para finalizar ese shell.
4. **Accede a tu computadora desde cualquier teléfono.** Usa el navegador de tu teléfono para
   vibe coding, correcciones rápidas, ejecutar comandos y más.

Para iniciar en un proyecto concreto, usa `uvx ptn /path/to/project`.
Para opciones de instalación, consulta [installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md), o usa un instalador a continuación.

> **El enlace es la llave de la computadora.** La URL completa y el código QR otorgan
> acceso al shell. Compártelos solo con personas y agentes de tu confianza.
> [Lee el modelo de seguridad](#security).

## El agente trabaja. Tú te mantienes al tanto.

| Tu agente | Tú |
|------------|-----|
| Ejecuta comandos en el shell real de la computadora | Observas la misma salida en vivo en un navegador |
| Lee las pantallas de la terminal y responde a los prompts | Escribes en la misma terminal cuando es necesario |
| Mantiene el estado del shell entre llamadas a herramientas | Alternas entre pestañas del agente y personales |
| Usa MCP o HTTP para conectarse | Usas el código QR o la URL desde un teléfono o escritorio |

La entrada de la terminal es compartida; coordina la escritura con tu agente. Porterminal
admite aplicaciones de terminal interactivas, múltiples pestañas y la reconexión a sesiones
en ejecución mientras el servidor y la sesión sigan activos.

La interfaz para teléfono incluye teclas Ctrl/Alt/Shift, selección táctil, desplazamiento,
zoom con pellizco y un campo de composición para editar o dictar entradas más largas.
Consulta [terminal controls](https://github.com/porterminal/porterminal/blob/master/docs/frontend_features.md).

## Prueba la demo

Dale a un agente un pequeño proyecto de facturas con una comprobación que falla. Observa cómo encuentra el
error, edita el archivo y hace que las comprobaciones pasen. Luego responde al prompt de la etiqueta del recibo
desde tu teléfono y haz que el agente lea el resultado.

La [demo guide](https://github.com/porterminal/porterminal/blob/master/docs/demo.md) incluye un proyecto listo para copiar, una tarea para el agente
y un plan de grabación de 60 segundos. Demuestra comandos, cambios de archivos,
verificación y entrada humana en una única sesión compartida.

## Conecta tu agente

Al pulsar **`c`** se copian las instrucciones para los métodos de conexión disponibles.
El servidor en ejecución también las sirve en `<url>/llms.txt`.

Aquí, **`<url>` es la URL completa generada, incluido su código de acceso**.

| Capacidad del agente | Conexión |
|------------------|------------|
| MCP remoto | `<url>/mcp` — Streamable HTTP |
| Solicitudes HTTP | `<url>/api/agent/run` — REST |
| Automatización del navegador | Abre `<url>/`; usa **Terminal screen** y **Terminal input** |

MCP expone cuatro herramientas: `run_command`, `read_screen`, `send_keys` y
`send_signal`. REST devuelve un `session_id` que el agente reutiliza para los comandos
e interacciones posteriores. Los shells del agente aparecen como pestañas 🤖 en tu navegador.

Consulta [agent access](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md) para la configuración del cliente, ejemplos de solicitudes,
duración de las sesiones y comandos de larga duración.

## Instalación

Requiere **Python 3.12+**. Porterminal intenta instalar `cloudflared`
automáticamente cuando falta.

| Método | Ejecutar o instalar | Actualizar |
|--------|----------------|--------|
| uvx | `uvx ptn` | `uvx --isolated ptn@latest` |
| uv tool | `uv tool install ptn` | `uv tool upgrade ptn` |
| pipx | `pipx install ptn` | `pipx upgrade ptn` |
| pip | `pip install ptn` | `pip install -U ptn` |

**Instala uv y Porterminal juntos:**

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/porterminal/porterminal/master/install.ps1 | iex"
```

macOS / Linux:

```bash
curl -LsSf https://raw.githubusercontent.com/porterminal/porterminal/master/install.sh | sh
```

## Uso

Después de instalar, ejecuta `ptn` o `ptn /path/to/project`.

| Opción | Propósito |
|--------|---------|
| `--no-tunnel` | Ejecutar sin un túnel de Cloudflare |
| `--mcp-only` | Exponer solo MCP; desactiva el código QR, la terminal del navegador y la API REST |
| `--compose` | Iniciar con el campo de composición móvil habilitado |
| `--init` | Generar `.ptn/ptn.yaml` con botones descubiertos a partir de los scripts del proyecto |
| `--password` | Añadir una contraseña al acceso de la terminal del navegador |
| `--help` | Mostrar todas las opciones |
| `--version` | Mostrar la versión instalada |

Durante la ejecución: **`c`** copia las instrucciones del agente, **`u`** copia solo la
URL, y **`s`** muestra el texto para compartir en pantalla (**`q`** lo cierra).
**Ctrl+C** detiene Porterminal. En el modo solo MCP, las teclas de compartir usan la URL de MCP.

Los shells personalizados, los botones de la barra de herramientas y la configuración de inicio se encuentran en `ptn.yaml`.
Consulta [configuration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md).

## Seguridad

Porterminal da acceso a un shell real con los permisos de tu usuario. El
directorio inicial es una comodidad, no un sandbox ni un límite al acceso a archivos.

Cada lanzamiento crea una nueva ruta de acceso aleatoria de 128 bits. El nombre de host del túnel sin ruta
y las rutas incorrectas devuelven 404, pero cualquiera que tenga la URL completa puede usar el shell.
Mantén la URL y el código QR en privado, detén Porterminal cuando termines y reinícialo
para rotar el código de acceso si el enlace se filtra.

**La contraseña opcional protege las conexiones del navegador. MCP y REST usan la
URL completa como credencial y no requieren esa contraseña.**

Consulta [security](https://github.com/porterminal/porterminal/blob/master/docs/security.md) para conocer el modelo completo y el comportamiento de la contraseña.
Reporta vulnerabilidades a través de [la política de seguridad](https://github.com/porterminal/porterminal/blob/master/.github/SECURITY.md).

## Documentación y desarrollo

- [Installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md)
- [Agent access: MCP, REST, and browser fallback](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md)
- [Demo setup and recording](https://github.com/porterminal/porterminal/blob/master/docs/demo.md)
- [Configuration](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md)
- [Architecture](https://github.com/porterminal/porterminal/blob/master/docs/architecture.md)
- [Development and release process](https://github.com/porterminal/porterminal/blob/master/docs/development.md)
- [Changelog](https://github.com/porterminal/porterminal/blob/master/docs/CHANGELOG.md)

Los informes de errores y las solicitudes de funciones son bienvenidos como
[issues](https://github.com/porterminal/porterminal/issues).
No se aceptan pull requests externos ni contribuciones de código; consulta
[CONTRIBUTING.md](https://github.com/porterminal/porterminal/blob/master/CONTRIBUTING.md). Puedes hacer un fork y ejecutar tu propia copia.

## Licencia

[AGPL-3.0](https://github.com/porterminal/porterminal/blob/master/LICENSE)