Configuración del Modo Remoto/Devcontainer

Lo que aprenderás

Usar Plannotator en un servidor remoto conectado por SSH
Configurar y acceder a Plannotator en un devcontainer de VS Code
Usar Plannotator en un entorno WSL (Windows Subsystem for Linux)
Configurar el reenvío de puertos para acceder a Plannotator desde tu navegador local

El problema que enfrentas

Estás usando Claude Code u OpenCode en un servidor remoto, devcontainer o entorno WSL. Cuando la IA genera un plan o necesita una revisión de código, Plannotator intenta abrir un navegador en el entorno remoto, pero no hay interfaz gráfica disponible, o prefieres ver la interfaz de revisión en tu navegador local.

Cuándo usar esta técnica

Escenarios típicos que requieren el modo Remoto/Devcontainer:

Escenario	Descripción
Conexión SSH	Te conectas a un servidor de desarrollo remoto vía SSH
Devcontainer	Desarrollas usando devcontainers en VS Code
WSL	Desarrollas en Linux usando WSL en Windows
Entorno en la nube	Tu código se ejecuta en un contenedor o máquina virtual en la nube

Concepto clave

Usar Plannotator en un entorno remoto requiere resolver dos problemas:

Puerto fijo: Los entornos remotos no pueden seleccionar automáticamente puertos aleatorios porque necesitas configurar el reenvío de puertos
Acceso al navegador: Los entornos remotos no tienen interfaz gráfica, por lo que necesitas acceder desde el navegador de tu máquina local

Plannotator entra automáticamente en "modo remoto" al detectar la variable de entorno PLANNOTATOR_REMOTE:

Usa un puerto fijo (19432 por defecto) en lugar de un puerto aleatorio
Omite la apertura automática del navegador
Muestra la URL en la terminal para que puedas acceder manualmente desde tu navegador local

🎒 Antes de empezar

Requisitos previos

Antes de comenzar este tutorial, asegúrate de:

Haber completado la Guía de inicio rápido
Tener instalado y configurado el plugin de Claude Code o el plugin de OpenCode
Comprender los conceptos básicos de configuración de SSH o devcontainer

Paso a paso

Paso 1: Comprender las variables de entorno del modo remoto

El modo remoto de Plannotator depende de tres variables de entorno:

Variable de entorno	Descripción	Valor por defecto
`PLANNOTATOR_REMOTE`	Habilita el modo remoto	No establecida (modo local)
`PLANNOTATOR_PORT`	Número de puerto fijo	Aleatorio (local) / 19432 (remoto)
`PLANNOTATOR_BROWSER`	Ruta personalizada del navegador	Navegador predeterminado del sistema

Por qué

PLANNOTATOR_REMOTE indica a Plannotator que está en un entorno remoto y no debe intentar abrir un navegador
PLANNOTATOR_PORT establece un puerto fijo para facilitar la configuración del reenvío de puertos
PLANNOTATOR_BROWSER (opcional) especifica la ruta del navegador a usar en tu máquina local

Paso 2: Configuración en un servidor remoto SSH

Configurar el reenvío de puertos SSH

Edita tu archivo de configuración SSH ~/.ssh/config:

bash

Host your-server
    HostName your-server.com
    User your-username
    LocalForward 9999 localhost:9999

Deberías ver:

Se ha añadido la línea LocalForward 9999 localhost:9999
Esto reenviará el tráfico del puerto local 9999 al puerto 9999 del servidor remoto

Establecer variables de entorno en el servidor remoto

Después de conectarte al servidor remoto, establece las variables de entorno en la terminal:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

Por qué

PLANNOTATOR_REMOTE=1 habilita el modo remoto
PLANNOTATOR_PORT=9999 usa el puerto fijo 9999 (coincide con el puerto en la configuración SSH)

Configuración persistente

Si establecer las variables de entorno manualmente cada vez que te conectas es tedioso, puedes añadirlas a tu archivo de configuración del shell (~/.bashrc o ~/.zshrc):

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Usar Plannotator

Ahora puedes usar Claude Code u OpenCode normalmente en el servidor remoto. Cuando la IA genere un plan o necesite una revisión de código:

bash

# En el servidor remoto, la terminal mostrará algo como:
[Plannotator] Server running at http://localhost:9999
[Plannotator] Access from your local machine: http://localhost:9999

Deberías ver:

La terminal muestra la URL de Plannotator
El entorno remoto no abre un navegador (comportamiento esperado)

Acceder desde tu navegador local

Abre en el navegador de tu máquina local:

http://localhost:9999

Deberías ver:

La interfaz de revisión de Plannotator se muestra correctamente
Puedes realizar revisiones de planes o código como si estuvieras en un entorno local

Punto de verificación ✅:

[ ] Reenvío de puertos SSH configurado
[ ] Variables de entorno establecidas
[ ] La terminal del servidor remoto muestra la URL
[ ] El navegador local puede acceder a la interfaz de revisión

Paso 3: Configuración en VS Code Devcontainer

Configurar el devcontainer

Edita tu archivo .devcontainer/devcontainer.json:

json

{
  "name": "Your Devcontainer",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },

  "forwardPorts": [9999]
}

Por qué

containerEnv establece las variables de entorno dentro del contenedor
forwardPorts indica a VS Code que reenvíe automáticamente los puertos del contenedor a tu máquina local

Reconstruir e iniciar el devcontainer

Abre la paleta de comandos de VS Code (Ctrl+Shift+P o Cmd+Shift+P)
Escribe Dev Containers: Rebuild Container y ejecútalo
Espera a que el contenedor termine de reconstruirse

Deberías ver:

VS Code muestra el estado del reenvío de puertos en la esquina inferior derecha (generalmente un pequeño icono)
Al hacer clic, puedes ver que "Port 9999" está reenviado

Usar Plannotator

Usa Claude Code u OpenCode normalmente en el devcontainer. Cuando la IA genere un plan:

bash

# Salida de la terminal del contenedor:
[Plannotator] Server running at http://localhost:9999

Deberías ver:

La terminal muestra la URL de Plannotator
El contenedor no abre un navegador (comportamiento esperado)

Acceder desde tu navegador local

Abre en el navegador de tu máquina local:

http://localhost:9999

Deberías ver:

La interfaz de revisión de Plannotator se muestra correctamente

Punto de verificación ✅:

[ ] Configuración del devcontainer con variables de entorno y reenvío de puertos añadida
[ ] Contenedor reconstruido
[ ] VS Code muestra que el puerto está reenviado
[ ] El navegador local puede acceder a la interfaz de revisión

Paso 4: Configuración en entorno WSL

La configuración del entorno WSL es similar a la conexión SSH, pero no necesitas configurar manualmente el reenvío de puertos: WSL reenvía automáticamente el tráfico de localhost al sistema Windows.

Establecer variables de entorno

Establece las variables de entorno en la terminal de WSL:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

Configuración persistente

Añade estas variables de entorno a tu archivo de configuración del shell de WSL (~/.bashrc o ~/.zshrc):

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Usar Plannotator

Usa Claude Code u OpenCode normalmente en WSL:

bash

# Salida de la terminal de WSL:
[Plannotator] Server running at http://localhost:9999

Deberías ver:

La terminal muestra la URL de Plannotator
WSL no abre un navegador (comportamiento esperado)

Acceder desde el navegador de Windows

Abre en el navegador de Windows:

http://localhost:9999

Deberías ver:

La interfaz de revisión de Plannotator se muestra correctamente

Punto de verificación ✅:

[ ] Variables de entorno establecidas
[ ] La terminal de WSL muestra la URL
[ ] El navegador de Windows puede acceder a la interfaz de revisión

Solución de problemas

Puerto ya en uso

Si ves un error como este:

Error: bind: EADDRINUSE: address already in use :::9999

Solución:

Cambia el número de puerto:

bash

export PLANNOTATOR_PORT=10000  # Usa un puerto que no esté en uso

O detén el proceso que está usando el puerto 9999:
bash
```
lsof -ti:9999 | xargs kill -9
```

El reenvío de puertos SSH no funciona

Si tu navegador local no puede acceder a Plannotator:

Lista de verificación:

[ ] El número de puerto en LocalForward del archivo de configuración SSH coincide con PLANNOTATOR_PORT
[ ] Te has desconectado y reconectado a SSH
[ ] El firewall no está bloqueando el reenvío de puertos

El reenvío de puertos del Devcontainer no funciona

Si VS Code no reenvía automáticamente el puerto:

Solución:

Verifica la configuración de forwardPorts en .devcontainer/devcontainer.json
Reenvía el puerto manualmente:
- Abre la paleta de comandos de VS Code
- Ejecuta Forward a Port
- Introduce el número de puerto 9999

No se puede acceder desde WSL

Si el navegador de Windows no puede acceder a Plannotator en WSL:

Solución:

Verifica que las variables de entorno estén configuradas correctamente
Intenta usar 0.0.0.0 en lugar de localhost (dependiendo de la versión de WSL y la configuración de red)
Verifica la configuración del firewall de Windows

Resumen

Puntos clave del modo Remoto/Devcontainer:

Punto clave	Descripción
Variables de entorno	`PLANNOTATOR_REMOTE=1` habilita el modo remoto
Puerto fijo	Usa `PLANNOTATOR_PORT` para establecer un puerto fijo (19432 por defecto)
Reenvío de puertos	SSH/Devcontainer requieren configuración de reenvío de puertos; WSL lo hace automáticamente
Acceso manual	El modo remoto no abre automáticamente el navegador; debes acceder manualmente desde tu navegador local
Persistencia	Añade las variables de entorno a los archivos de configuración para evitar configuraciones repetidas

Próxima lección

En la próxima lección aprenderemos sobre la Guía detallada de variables de entorno.
Aprenderás:
Todas las variables de entorno disponibles en Plannotator
El propósito y valor por defecto de cada variable de entorno
Cómo combinar variables de entorno para diferentes escenarios

Apéndice: Referencia del código fuente

Haz clic para ver la ubicación del código fuente

Última actualización: 2026-01-24

Funcionalidad	Ruta del archivo	Líneas
Detección de sesión remota	`packages/server/remote.ts`	16-29
Obtención del puerto del servidor	`packages/server/remote.ts`	34-49
Lógica de inicio del servidor	`packages/server/index.ts`	91-97
Lógica de apertura del navegador	`packages/server/browser.ts`	45-74
Detección de WSL	`packages/server/browser.ts`	11-34

Constantes clave:

DEFAULT_REMOTE_PORT = 19432: Puerto por defecto del modo remoto

Funciones clave:

isRemoteSession(): Detecta si se está ejecutando en una sesión remota
getServerPort(): Obtiene el puerto del servidor (puerto fijo para remoto, aleatorio para local)
openBrowser(url): Abre el navegador de forma multiplataforma

Configuración del Modo Remoto/Devcontainer ​

Lo que aprenderás ​

El problema que enfrentas ​

Cuándo usar esta técnica ​

Concepto clave ​

🎒 Antes de empezar ​

Paso a paso ​

Paso 1: Comprender las variables de entorno del modo remoto ​

Paso 2: Configuración en un servidor remoto SSH ​

Configurar el reenvío de puertos SSH ​

Establecer variables de entorno en el servidor remoto ​

Usar Plannotator ​

Acceder desde tu navegador local ​

Paso 3: Configuración en VS Code Devcontainer ​

Configurar el devcontainer ​

Reconstruir e iniciar el devcontainer ​

Usar Plannotator ​

Acceder desde tu navegador local ​

Paso 4: Configuración en entorno WSL ​

Establecer variables de entorno ​

Usar Plannotator ​

Acceder desde el navegador de Windows ​

Solución de problemas ​

Puerto ya en uso ​

El reenvío de puertos SSH no funciona ​

El reenvío de puertos del Devcontainer no funciona ​

No se puede acceder desde WSL ​

Resumen ​

Próxima lección ​

Apéndice: Referencia del código fuente ​

Configuración del Modo Remoto/Devcontainer

Lo que aprenderás

El problema que enfrentas

Cuándo usar esta técnica

Concepto clave

🎒 Antes de empezar

Paso a paso

Paso 1: Comprender las variables de entorno del modo remoto

Paso 2: Configuración en un servidor remoto SSH

Configurar el reenvío de puertos SSH

Establecer variables de entorno en el servidor remoto

Usar Plannotator

Acceder desde tu navegador local

Paso 3: Configuración en VS Code Devcontainer

Configurar el devcontainer

Reconstruir e iniciar el devcontainer

Usar Plannotator

Acceder desde tu navegador local

Paso 4: Configuración en entorno WSL

Establecer variables de entorno

Usar Plannotator

Acceder desde el navegador de Windows

Solución de problemas

Puerto ya en uso

El reenvío de puertos SSH no funciona

El reenvío de puertos del Devcontainer no funciona

No se puede acceder desde WSL

Resumen

Próxima lección

Apéndice: Referencia del código fuente