Docs

Instalar y usar Glassys

Glassys corre en la máquina que debe operar el agente, como un servicio de tu propio usuario. Aquí están los pasos, los ajustes y las recetas para abrirlo desde el móvil.

Requisitos

Node.js 22.13+ y pnpm 11.14+ (el repositorio es un workspace de pnpm; no uses npm). Con Node 25+, instala antes Corepack con npm install -g corepack.
Un workspace git en la máquina que ejecutará el agente.
macOS (launchd) o Linux (systemd --user).
El login del SDK de tu agente en ese host. Con Cursor, inicia sesión con el SDK de Cursor en el asistente; la API key es opcional.

Instalación

Una línea, desde cualquier directorio. Clona el repositorio si hace falta, ejecuta pnpm install, construye e instala un servicio de usuario: launchd en macOS, systemd --user en Linux. Cerrar la terminal no para Glassys.

bash

$ curl -fsSL https://raw.githubusercontent.com/KN990x/Glassys/main/scripts/install.sh | bash

Lo mismo, a mano:

bash

$ git clone https://github.com/KN990x/Glassys.git glassys && cd glassys && pnpm install && pnpm run service:install

Primer arranque

1Abre http://127.0.0.1:8787 en el host (o el puerto de GLASSYS_PORT).
2Pon la contraseña de operador. Quien la pone se queda con la instancia.
3Elige el adaptador y la ruta absoluta del workspace.
4Inicia sesión en el SDK del agente. En un host sin pantalla (SSH, systemd), el asistente muestra una URL de login para abrirla donde estés.

La configuración desde otro dispositivo, o a través de un reverse proxy, pide el código de configuración de un solo uso que imprime el instalador. También está en el log del gateway y en $GLASSYS_DATA_DIR/setup-code hasta terminar. Desde un navegador en el propio host no hace falta.

Gestionar el servicio

Ejecútalos desde el clon con el que instalaste. Actualizar es git pull --ff-only, instalar, construir y reiniciar, y comprueba que /health da el commit nuevo. Si el pull falla, se detiene en vez de reconstruir el clon viejo.

bash

$ cd glassys && pnpm run service:status
$ cd glassys && pnpm run service:upgrade
$ cd glassys && pnpm run service:uninstall

Linux: la unidad es ~/.config/systemd/user/glassys.service. En un host sin pantalla, activa linger para que cerrar la sesión no la pare, y lee sus logs en el journal:

bash

$ sudo loginctl enable-linger $USER
$ journalctl --user -u glassys

macOS: un LaunchAgent en ~/Library/LaunchAgents/dev.kn990x.glassys.plist con KeepAlive.

Para depurar una vez en primer plano (cerrar la terminal lo para):

bash

$ pnpm run build && pnpm start

Desinstalar para el servicio y quita la unidad. No borra el clon ni data/.

Ábrelo desde el móvil

El gateway escucha en 127.0.0.1. Para una URL pública, termina TLS delante y reenvía HTTP y el WebSocket (/ws) a 127.0.0.1:8787. Glassys es la app detrás del proxy, no el proxy.

Caddy

Caddy 2 actualiza los WebSockets en el mismo reverse_proxy. Cambia el nombre de host por el tuyo.

Caddyfile

your.example.com {
	encode gzip
	reverse_proxy 127.0.0.1:8787
}

Cloudflare Tunnel y Access

Apunta un túnel a http://127.0.0.1:8787 con WebSockets activados. Access es opcional y va encima: pon security.edgeAuth: cloudflare-access con tu dominio de equipo y la audiencia. Glassys sigue pidiendo su propia contraseña de operador. Con Access apagado, Glassys nunca llama a Cloudflare.

Con un proxy en el mismo host, todas las peticiones llegan a Glassys desde 127.0.0.1. Pon network.trustProxy: true (o GLASSYS_TRUST_PROXY=1) para que los límites de login se apliquen por visitante. Mantén altos los tiempos de inactividad: una ejecución dura minutos, y Glassys hace ping al socket cada 25 s.

Las notificaciones push necesitan HTTPS (o localhost), e iOS solo las entrega a una app instalada: abre la web en Safari y añádela a la pantalla de inicio.

docs/deploy/caddy.md docs/deploy/cloudflare.md

Configuración

Todo lo que no es secreto vive en $GLASSYS_DATA_DIR/config.yaml, que se crea con valores por defecto en el primer arranque (ver config.example.yaml). Los Ajustes de la app escriben idioma, tema, agente, pantalla y sesión; el bind, el puerto, los orígenes permitidos, trustProxy y la autenticación de borde son solo yaml o entorno.

Los secretos —las API keys opcionales por adaptador, el hash de la contraseña y el secreto JWT— viven en variables de entorno o en $GLASSYS_DATA_DIR/secrets.json. La app puede mostrar configurado / rotar, nunca la clave completa otra vez.

Variables de entorno

Variable	Para qué sirve
`GLASSYS_DATA_DIR`	Dónde viven la config, los secretos, los transcripts y las programaciones (por defecto: data/ en el clon).
`GLASSYS_BIND`	Dirección en la que escucha (por defecto 127.0.0.1).
`GLASSYS_PORT`	Puerto en el que escucha (por defecto 8787).
`GLASSYS_TRUST_PROXY`	Ponla a 1 detrás de un reverse proxy en el mismo host.
`GLASSYS_WEB_DIR`	Servir la app desde otro build.
`GLASSYS_NODE`	El binario de node que ejecuta el servicio instalado.
`GLASSYS_OPERATOR_PASSWORD_HASH`	Fija el hash de la contraseña; entonces solo se cambia aquí.
`GLASSYS_JWT_SECRET`	Fija el secreto con el que se firman las sesiones.

Claves opcionales de los adaptadores: CURSOR_API_KEY, ANTHROPIC_API_KEY, CODEX_API_KEY / OPENAI_API_KEY, OPENCODE_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY. El instalador nunca las copia en la unidad.

config.example.yaml

Agentes

Glassys habla con cada agente a través de su SDK local o de ACP, nunca en print-mode, que oculta el razonamiento. El CLI del proveedor puede seguir instalado: su login no autentica Glassys.

Agente	Cómo llega Glassys
Cursor	@cursor/sdk en el host, no cursor-cli ni cursor-agent. Inicia sesión con el SDK de Cursor o define CURSOR_API_KEY.
Claude Code	Claude Agent SDK.
OpenCode	SDK de OpenCode y un servidor local; necesita el binario opencode en el PATH.
Codex	SDK de Codex, con el binario de Codex que trae.
Gemini	Con el adaptador ACP (gemini --acp) hasta que el SDK de Gemini CLI esté en npm.
Cualquier agente ACP	El host ACP genérico ejecuta agentes del registro ACP.

No lances dos agentes con auto-run a la vez sobre el mismo directorio de trabajo; por ejemplo, el CLI en una terminal y Glassys sobre los mismos archivos.

Seguridad

Glassys con auto-run y un workspace del host es acceso de operador a esa máquina.
La autenticación de operador va siempre, también detrás de Cloudflare Access.
El sandbox y el auto-run se ven en Ajustes. Con el auto-run apagado, Cursor usa Auto-review, que deniega las llamadas arriesgadas, y ACP deniega escrituras y terminales.
Deja el workspace fuera del directorio de datos de Glassys. Claude y ACP rechazan las herramientas que entran ahí; Cursor, Codex, OpenCode y Gemini ejecutan sus herramientas en su propio proceso, así que con ellos solo un sandbox o un workspace aparte mantienen fuera al agente.
No escuches en 0.0.0.0 salvo que el proxy sea la única cara pública.

Leer SECURITY.md