# La Consola

> Qué muestra la única página integrada del motor, cómo abrirla con un token de API, cómo protegerla o apagarla, y qué no hace frente a la app de Sypnia Cloud.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/self-hosting/console/

Para agentes: La Consola es la única página web integrada del motor de Sypnia con alojamiento propio, en <URL base>/console: una lista de problemas con el análisis y el prompt de cada uno, las alertas sin reconocer, y una lista de sesiones con línea de tiempo y visor de grabaciones. Se entra con un token de API (read, más replay para las grabaciones), nunca con el token raíz. Cómo protegerla (tokens por persona, reglas en el proxy, SYPNIA_CONSOLE_ENABLED=false) y qué tiene solo la app de Sypnia Cloud.

**\[Motor]** Esta página es para quien usa o protege un motor con alojamiento propio. La Consola existe solo en el motor de código abierto. Sypnia Cloud tiene en su lugar la app completa, en `app.sypnia.com`, y no tiene Consola.

> **En palabras simples**
>
> La Consola es una sola página web que viene dentro del motor. Muestra qué está roto y te deja ver la visita en la que se rompió. Es pequeña a propósito: todo lo demás que Sypnia sabe está disponible como datos, para que lo lean tu agente de código o tus propias herramientas.

La Consola no tiene datos propios. Lee por la misma [API](https://docs.sypnia.com/es/api) que todo lo demás, con el token que le das, así que muestra exactamente lo que ese token puede leer y nada más.

## Abrirla

**Al final tendrás:** los problemas de un proyecto en tu pantalla.

### 1. Crea un token para ti

A la Consola se entra con un token de API. `read` muestra los problemas, las sesiones y sus líneas de tiempo; agrega `replay` para ver grabaciones.

```bash
sypnia token create --project shop --name "Console, Ana" --scopes read,replay --expires 90d
```

**Deberías ver:**Una línea que empieza por `sps_`. Se muestra una sola vez.

### 2. Abre la página y pega el token

Ve a `<tu URL base>/console`, por ejemplo `https://sypnia.example.com/console`, y pega el token.

**Deberías ver:**La lista de problemas del proyecto al que pertenece el token, para el entorno `production`. Para ver tus propias pruebas, elige `development` arriba.

Qué pasa con el token:

- Se queda en esa pestaña del navegador y se olvida cuando la cierras. La Consola no pone cookies ni guarda nada en el servidor.
- Se envía solo a tu motor, como el encabezado `Authorization` de las llamadas a la API.
- Un token pertenece a un proyecto, así que la Consola muestra un proyecto a la vez. Para otro proyecto, pega el token de ese proyecto.
- El token raíz se rechaza. Puede eliminar proyectos, y su lugar no es un navegador.

## Qué muestra

**Figura (diagrama aún sin dibujar)**: La Consola: las alertas que nadie ha reconocido, la lista de problemas, y un problema con su causa, su prompt y las sesiones que afectó.

Mostrará: La misma maqueta de pantalla que la figura 1 de la página en inglés (self-hosting/console), con las mismas regiones, llamadas numeradas (1) a (4) y el mismo elemento encendido (la primera fila de la lista). Rótulos traducidos: barra superior «Consola de Sypnia», proyecto «shop», selector de entorno «production», pestañas «Problemas» (activa) y «Sesiones», enlace «Salir»; franja «1 alerta sin reconocer» con la fila «Problema nuevo · 09:13 · 3 personas intentaron pagar hoy y no pudieron…» y el botón «Reconocer»; lista de problemas: fila 1 marca «nuevo», frase «3 personas intentaron pagar hoy y no pudieron. El botón Pagar no hace nada desde el cambio de ayer.», debajo «3 personas · desde hoy 09:12 · versión 4f2a91c»; fila 2 marca «volvió», «La página de búsqueda muestra una lista vacía a algunas personas.», «12 personas · desde el lunes»; fila 3 sin marca, título técnico sin traducir, «1 persona · desde ayer»; detalle del problema con los bloques «A quién», «Desde cuándo», «Causa (confianza: alta)», «Evidencia» (con «src/checkout/checkout.tsx:142»), «Qué hacer», los botones «Copiar prompt», «Resolver», «Ignorar», y «Sesiones que afectó» con el enlace «Ver grabación».

### Problemas

La lista muestra los problemas del proyecto, con la actividad más reciente primero: la frase en palabras simples, o el título técnico cuando el agente está apagado; las marcas «nuevo», «creciendo» y «volvió»; a cuántas personas afectó; desde cuándo; y la versión. Puedes filtrar por estado y entorno, y buscar en el texto.

Al abrir un problema ves:

- **El análisis**, cuando hay un proveedor de IA conectado: a quién afectó, desde cuándo, la causa probable con su evidencia, qué hacer, y qué tan seguro está el agente.
- **La falla misma**: el stack, en tus propios archivos y líneas cuando la versión tiene source maps; qué hizo la persona antes; y la traza, como una lista de pasos con sus tiempos.
- **Las sesiones que afectó**, cada una con un enlace a su grabación.
- **Copiar prompt**: [el prompt listo](https://docs.sypnia.com/es/agent/the-prompt) para tu agente de código, el mismo texto que imprime `sypnia problem --prompt`.
- **Resolver** y **Reabrir**. **Ignorar** y **Analizar de nuevo** aparecen solo cuando el token tiene el alcance `admin`.

### Alertas

Las alertas que nadie ha reconocido quedan en una franja sobre la lista, la más nueva primero, cada una con un botón **Reconocer**. Una alerta sobre un problema abre ese problema. Las alertas de disponibilidad, de una página más lenta, de una ruta de API que falla o de uso muestran su título y sus números, y nada más: la Consola no tiene pantalla para eso. Los datos están en la [API](https://docs.sypnia.com/es/api/webhooks).

### Sesiones y el visor de grabaciones

La segunda pestaña lista las sesiones recientes: quién, cuándo, cuántas páginas, y si algo salió mal. Puedes dejar solo las sesiones con problemas o con grabación, y encontrar una por id de persona o id de sesión.

Al abrir una sesión ves su línea de tiempo, en orden: páginas, clics, clics de rabia, clics muertos, errores, peticiones fallidas. Si la sesión tiene grabación y tu token tiene el alcance `replay`, el visor la reproduce junto a la línea de tiempo: reproducir, pausar, cambiar la velocidad, y saltar a cualquier evento de la línea de tiempo.

- Una grabación se puede ver cuando su sesión lleva 2 minutos inactiva o ya terminó.
- Lo que una persona escribió son asteriscos, y las áreas enmascaradas están en blanco. La Consola no puede mostrar lo que el navegador nunca envió. Ver [Enmascarado](https://docs.sypnia.com/es/privacy/masking).
- El visor trae la grabación directo de tu bucket, con enlaces firmados que funcionan 15 minutos (`SYPNIA_STORAGE_PRESIGN_TTL_SECONDS`). El bucket sigue siendo privado.
- La Consola no carga el SDK, así que nunca se graba a sí misma.

## Qué no hace

La Consola es una sola página a propósito. Esto es lo que tiene la app de Sypnia Cloud y la Consola no:

|                                                                                                     | La Consola **\[Motor]**                                        | La app de Sypnia Cloud **\[Nube]**                                                     |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Problemas con su análisis y su prompt                                                               | Sí                                                             | Sí                                                                                     |
| Grabación de sesiones                                                                               | Un visor: reproducir, pausar, velocidad, saltar a un evento    | El reproductor completo, con el momento en que se rompió marcado en la línea de tiempo |
| Rendimiento: páginas lentas, llamadas de API lentas o que fallan, el elemento detrás de una métrica | No. [API](https://docs.sypnia.com/es/api/performance) y MCP    | Pantallas                                                                              |
| Mapas de clics, clics de rabia y muertos por página                                                 | No. API                                                        | Pantallas                                                                              |
| Trazas                                                                                              | La traza de un problema, como lista                            | Una cascada para cualquier petición                                                    |
| Disponibilidad                                                                                      | No. [API](https://docs.sypnia.com/es/api/uptime)               | Pantallas                                                                              |
| Búsqueda en todo                                                                                    | Búsqueda de texto en problemas; sesiones por id                | Un solo buscador                                                                       |
| Actividad de personas y cuentas                                                                     | No. [API](https://docs.sypnia.com/es/api/sessions-and-replays) | Pantallas                                                                              |
| El resumen diario y las sugerencias semanales                                                       | No. `GET /v1/summary` y `GET /v1/suggestions`                  | En la app y por correo                                                                 |
| Configuración del proyecto, llaves, tokens, reglas de alerta, webhooks                              | No. La [CLI](https://docs.sypnia.com/es/cli) y la API          | Pantallas                                                                              |
| Entrar                                                                                              | Un token de API, un proyecto a la vez                          | Cuentas, organizaciones y roles                                                        |
| Un enlace que le puedes mandar a un colega                                                          | Le abre a quien tenga su propio token de ese proyecto          | Le abre a los miembros de la organización                                              |
| Pull requests                                                                                       | No                                                             | Un botón en el problema                                                                |

Nada de la columna izquierda se te esconde: todo está en la API, la CLI y el servidor MCP. La Consola solo elige no dibujarlo.

## Protegerla

Sin un token la Consola no muestra nada: la página es un cascarón vacío, y los datos están detrás de la API. Proteger la Consola es entonces, sobre todo, proteger los tokens. Haz esto en orden.

### 1. Dale a cada persona su propio token

Un token por persona, con los menos alcances posibles y una fecha de vencimiento. `replay` deja a quien lo tiene ver lo que tus usuarios vieron en sus pantallas: dalo solo a quien deba.

```bash
sypnia token create --project shop --name "Console, Ana" --scopes read,replay --expires 90d
sypnia token list --project shop
```

**Deberías ver:**La lista muestra quién tiene qué, y cuándo se usó cada token por última vez. Revoca uno con `sypnia token revoke`; deja de funcionar en menos de un minuto.

### 2. Decide quién puede siquiera cargar la página

Por defecto la Consola está en una dirección pública. Para cerrarla a todo el que no sea de tu equipo, agrega una regla en el proxy que está delante del motor, solo para la ruta `/console`. Los SDK y los clientes de la API tienen que seguir llegando a `/v1`.

Con el Caddy de [Desplegar con Docker](https://docs.sypnia.com/es/self-hosting/deploy-docker), genera el hash de una contraseña y agrega cuatro líneas:

```bash
docker compose exec caddy caddy hash-password
```

`Caddyfile`

```text
{$SYPNIA_DOMAIN} {
	@console path /console /console/*
	basic_auth @console {
		team <el hash>
	}
	reverse_proxy sypnia:8080
}
```

**Deberías ver:**Después de `docker compose restart caddy`, el navegador pide el nombre `team` y la contraseña antes de mostrar la Consola, y luego la Consola pide el token como antes.

En AWS, la dirección es una distribución de CloudFront: asóciale una regla de AWS WAF que permita `/console*` solo desde las direcciones de tu oficina o tu VPN. AWS cobra un WAF por mes.

### 3. O apágala

Si tu equipo lee con un agente de código y la CLI, puede que no necesites la página.

```bash
SYPNIA_CONSOLE_ENABLED=false
```

**Deberías ver:**Después de reiniciar, `<tu URL base>/console` responde `404`. La API, el servidor MCP y la CLI no cambian. Los enlaces de las alertas siguen apuntando a la Consola, y dejan de funcionar.

Además, configura `SYPNIA_API_CORS_ORIGINS` solo si una app web tuya tiene que llamar a la API de lectura desde un navegador. La Consola no necesita nada ahí: está en la misma dirección del motor.

## Cuando algo no aparece

| Lo que ves                                                                           | Por qué                                                                                                                     | Qué hacer                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `404` en `/console`                                                                  | La Consola está apagada, o este proceso corre sin el rol `api`.                                                             | `SYPNIA_CONSOLE_ENABLED`, y el rol de [`sypnia serve`](https://docs.sypnia.com/es/cli/commands).                                                                                                                                                                               |
| «Este token no puede entrar»                                                         | El token fue revocado, venció, está mal escrito, o es el token raíz o una llave de ingesta.                                 | Crea un token de API.                                                                                                                                                                                                                                                          |
| Una lista de problemas vacía, y esperabas uno                                        | El entorno. Una prueba desde `localhost` normalmente cae en `development`.                                                  | Cambia el entorno arriba.                                                                                                                                                                                                                                                      |
| Un problema que solo tiene título técnico                                            | No hay proveedor de IA conectado, o se alcanzó el límite de análisis del día.                                               | [Modelos y qué se envía](https://docs.sypnia.com/es/agent/models-and-what-is-sent).                                                                                                                                                                                            |
| Una sesión sin enlace «Ver grabación»                                                | No se grabó: por defecto se graba el 10 % de las sesiones, más toda sesión con un error, un clic de rabia o un clic muerto. | [Sesiones y grabación](https://docs.sypnia.com/es/concepts/sessions-and-replay).                                                                                                                                                                                               |
| «Necesitas el alcance replay»                                                        | El token solo tiene `read`.                                                                                                 | Crea un token con `read,replay`.                                                                                                                                                                                                                                               |
| «Todavía no está lista» en una grabación                                             | La sesión sigue en curso.                                                                                                   | Espera a que lleve 2 minutos inactiva.                                                                                                                                                                                                                                         |
| «Venció» en una sesión o una grabación                                               | Es más vieja que tu retención.                                                                                              | [Retención](https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention#retenci%C3%B3n).                                                                                                                                                                                |
| El visor se queda vacío y la consola del navegador muestra un error de CORS o de red | El navegador no puede leer del bucket.                                                                                      | Revisa `SYPNIA_STORAGE_PUBLIC_ENDPOINT`, y la [regla del bucket](https://docs.sypnia.com/es/self-hosting/deploy-docker#dejar-que-los-navegadores-lean-grabaciones-de-un-bucket-alojado) si es un bucket alojado. Prueba sin extensiones del navegador que bloqueen peticiones. |

## Relacionado
