PiAgentUI/README.es.md

Issues · Changelog · Specs de diseño

English · Português (BR) · Español · 日本語

Qué es

PiAgentUI es una interfaz de chat y un workspace para el agente de código Pi. Funciona como app web servida por una extensión de Pi o como app de escritorio con Tauri 2, y muestra en una ventana lo que una terminal sola esconde: la lista de sesiones, las tool calls, los servidores MCP, las skills y el uso de contexto.

• Transmite sesiones reales de Pi por SSE (/global/event) y renderiza Markdown, código (Shiki) y matemáticas (KaTeX).
• Muestra las tool calls como tarjetas y el uso de contexto de la sesión activa.
• Cambia de modelo con las capacidades que informa el runtime.
• Lista los servidores MCP configurados (transporte, comando, URL, origen) y las skills efectivas agrupadas por origen.
• Expone slash commands integrados y dinámicos, además de controles de Git en el composer.
• Integra una terminal (xterm.js) y un explorador de archivos junto al chat.
• Acepta entrada de voz mediante un endpoint STT compatible con OpenAI configurado en settings.
• Idiomas de la interfaz: en, pt-BR, es, zh-CN, hi, bn, ar (src/locales/).

Por qué usarlo

PiAgentUI no guarda estado propio del agente. Sesiones, modelos, tools, skills y comandos vienen del runtime de Pi a través de la extensión, así que lo que ves es lo que Pi está ejecutando.

No lo uses si no ejecutas Pi: sin la extensión, la interfaz solo muestra el diálogo de conexión al servidor. También atiende un runtime por ventana y no tiene demo alojada ni paquete publicado en npm.

Cómo funciona

• extensions/piagentui-server.ts es la extensión de Pi. Sirve la UI compilada desde dist/ con http + ws de Node e inyecta window.PI_BOOT_DATA (URL base y token).
• Al arrancar escucha en el puerto 58785 (o el siguiente libre) y escribe el puerto y un token aleatorio en ~/.pi/agent/piagentui-port.json.
• GET /global/health es abierto; las demás rutas /api/* exigen Authorization: Bearer <token>. El socket escucha en 0.0.0.0, pero cada petición se valida contra loopback salvo que el acceso por LAN en /api/network/access esté activado (viene desactivado).
• La app Tauri lee el mismo archivo de descubrimiento con el comando get_pi_agent_connection, así que el build de escritorio se conecta al runtime local sin configuración manual.
• En contenedores, el router en Rust (src-router/, axum) va detrás de Caddy como gateway delante de los servicios de frontend y backend.

Inicio rápido

Herramienta	Versión	Necesaria para
Node.js	>=22 (.tool-versions: 22.22.0)	todo
npm	la que trae Node	todo (package-lock.json)
Rust	1.85.0 (.tool-versions)	app de escritorio y router del gateway
Docker Compose	reciente	solo el stack de contenedores
Pi Agent	instalado localmente	sesiones y modelos reales

git clone https://git.evandro.dev.br/evandro/PiAgentUI.git
cd PiAgentUI
npm ci          # el postinstall ejecuta scripts/copy-material-icons.mjs
npm run build   # tsc -b && vite build -> dist/
npm run dev     # servidor Vite en http://localhost:5173

npm run dev es solo el front end: hace proxy de /api a 127.0.0.1:4096 sin el prefijo. Para el flujo con Pi, compila primero y deja que la extensión sirva dist/ (Pi carga este repositorio como paquete mediante el campo pi.extensions de package.json):

npm run build
cat ~/.pi/agent/piagentui-port.json   # {"port": 58785, "token": "..."}
# abre http://127.0.0.1:58785

Escritorio y Android:

npm run tauri dev                 # ventana de escritorio sobre el servidor Vite
npm run tauri build               # bundles: nsis, dmg, deb (src-tauri/tauri.conf.json)
npm run tauri android dev         # ver scripts/dev-android.sh

Antes de un PR, npm run validate ejecuta typecheck, typecheck de la extensión, lint, build y tests; es el gate que corre el CI en build.yml.

Configuración

El stack de contenedores viene heredado del despliegue de OpenCodeUI. Copia .env.example a .env primero.

Archivo	Comando	Qué hace
docker-compose.yml	docker compose up -d	Stack completo: gateway (Caddy + router en Rust, 127.0.0.1:6658 y 6659), frontend, backend (opencode serve, 4096, límite de 4G de memoria).
docker-compose.standalone.yml	docker compose -f docker-compose.standalone.yml up -d	Solo el front end, para un opencode serve existente. Usa BACKEND_URL (por defecto host.docker.internal:4096) y PORT (por defecto 3000).
docker-compose.host.yml	docker compose -f docker-compose.yml -f docker-compose.host.yml up -d	Override opcional: el backend corre privilegiado, con el socket de Docker y el / del host montado en /host.
docker-compose.build.yml	docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build	Override opcional: compila gateway, frontend y backend localmente desde docker/.

Variables de entorno (solo para el stack de contenedores)

Variable	Obligatoria	Descripción
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, XAI_API_KEY	Al menos una	Claves de proveedores de LLM que se pasan al contenedor del backend.
GATEWAY_PORT	No (6658)	Puerto del host para el punto de entrada unificado.
PREVIEW_PORT	No (6659)	Puerto del host para el punto de entrada de previews.
PREVIEW_DOMAIN	No	Dominio aparte para previews; el proxy inverso lo reenvía a PREVIEW_PORT.
WORKSPACE	No (./workspace)	Carpeta del host montada en /workspace en el backend.
OPENCODE_SERVER_PASSWORD	En despliegues públicos	Contraseña del backend y del router.
OPENCODE_SERVER_USERNAME	No (opencode)	Usuario que acompaña a la contraseña anterior.
PUBLIC_BASE_URL	No	URL base pública que usa el router integrado en el gateway.
ROUTER_SCAN_INTERVAL	No (5)	Intervalo de escaneo del router.
ROUTER_TOKEN_LENGTH	No (12)	Longitud de los tokens de ruta generados.
ROUTER_PORT_RANGE	No (3000-9999)	Rango de puertos que atiende el router.
ROUTER_EXCLUDE_PORTS	No (4096)	Puertos que el router omite.
DOCKER_API_VERSION	No (1.40)	Versión de la API de Docker para el backend; se define en docker-compose.yml, no en .env.example.
USE_CHINA_MIRROR	No (1)	Opción de build de la imagen del backend: usa los mirrors de abajo.
APT_MIRROR, APT_SECURITY_MIRROR, NPM_CONFIG_REGISTRY, NODEJS_ORG_MIRROR, PIP_INDEX_URL, PIP_TRUSTED_HOST	No	Mirrors para el toolchain del backend.
MISE_INSTALL_URL, OPENCODE_INSTALL_URL	No	URLs de instalación usadas al compilar la imagen del backend.

Estado del proyecto

Beta, antes de la 1.0 (0.6.10), mantenido por un desarrollador. Las releases salen de release.yml en tags v* (artefactos para Windows, macOS, Linux y Android); deploy.yml publica el build web con VITE_BASE_PATH=/PiAgentUI/.

• El nombre OpenCodeUI no ha desaparecido del todo: el crate del router en Rust es opencodeui-router, las imágenes son opencodeui-*, los APK de Android salen como OpenCodeUI-*, los comentarios de .env.example están en chino y el backend Docker ejecuta opencode serve, que pertenece al despliegue heredado, no al flujo con la extensión de Pi.
• docker-compose.yml y docker-compose.standalone.yml todavía descargan la imagen upstream ghcr.io/lehhair/opencodeui-frontend.
• Los tests son de componente y de servidor (Vitest). No hay tests del shell Tauri ni del router en Rust más allá de la compilación, ni test end-to-end en navegador, ni umbral de cobertura.
• La entrada de voz necesita un endpoint STT compatible con OpenAI y no tiene test automatizado en navegador.

Issues y pull requests van al issue tracker; ejecuta npm run validate antes de abrir un PR.

Licencia

GPL-3.0-only, ver LICENSE. PiAgentUI es un fork reelaborado de OpenCodeUI; el autor original figura en src-tauri/Cargo.toml.

---

_{Hecho por Evandro Fonseca Junior · git.evandro.dev.br}