Seguridad

Theus es una herramienta local-first: tus datos, tu índice y tu configuración viven en tu máquina, y cada acción capaz de modificar tu proyecto pasa por tu aprobación explícita.

El modelo de seguridad de Theus se apoya en cuatro pilares: mantener los datos en local, pedir permiso antes de cualquier operación destructiva, confirmar la confianza de cada carpeta antes de trabajar en ella, y exponer el API local únicamente en localhost protegido por un token de sesión.

Local-first: tus datos no salen de tu máquina

Theus construye y persiste su conocimiento del proyecto en tu directorio personal, bajo ~/.theus/. El índice, el grafo del proyecto y las incrustaciones se guardan por proyecto:

~/.theus/knowledge/<hash-del-proyecto>/graph.json        # nodos + aristas del grafo
~/.theus/knowledge/<hash-del-proyecto>/embeddings.json   # vectores por nodo

La configuración y el estado de Theus se almacenan también en ~/.theus/ (por ejemplo ~/.theus/providers.json para tus proveedores de modelo). A nivel de proyecto, las reglas de permisos y los ajustes se leen desde .theus/settings.json y .theus/settings.local.json dentro del propio repositorio.

Puedes cambiar la raíz de configuración/estado con la variable de entorno correspondiente; por defecto es ~/.theus.

Sistema de permisos para herramientas destructivas

Antes de ejecutar una operación que pueda modificar tu sistema —escribir o editar archivos, correr comandos de shell, editar notebooks, hacer peticiones web— Theus muestra un diálogo de permiso. Nada se ejecuta hasta que tú lo apruebas.

Las reglas de permiso tienen tres comportamientos:

Comportamiento	Efecto
`allow`	Permite la acción sin volver a preguntar.
`ask`	Pide confirmación cada vez.
`deny`	Bloquea la acción por completo.

Cada herramienta declara sus permisos y su carácter destructivo de forma precisa, y existen diálogos específicos para cada tipo de operación (edición de archivos, escritura, comandos de shell, uso de sandbox, edición de notebooks, peticiones web, entre otros). Las reglas se organizan por ámbito —allow, ask, deny y directorios de trabajo (workspace)— y se persisten en los ajustes del proyecto, de modo que puedes preaprobar patrones seguros y prohibir los peligrosos.

Concede allow solo a patrones que entiendas y consideres seguros. Un allow demasiado amplio (por ejemplo sobre comandos de shell) reduce las confirmaciones pero también las salvaguardas.

Diálogo de confianza de carpeta

La primera vez que abres Theus en una carpeta, aparece una comprobación de confianza. El diálogo muestra la ruta exacta del directorio actual y te pregunta si es un proyecto que creaste o en el que confías:

Comprobación rápida de seguridad: ¿Es este un proyecto que creaste o en el que confías? (Como tu propio código, un proyecto de código abierto conocido o trabajo de tu equipo). Si no, tómate un momento para revisar primero el contenido de esta carpeta.

El diálogo advierte de forma explícita que Theus podrá leer, editar y ejecutar archivos aquí, y ofrece dos opciones: Sí, confío en esta carpeta o No, salir. Si la carpeta define servidores MCP, hooks o reglas de permiso propias (por ejemplo en .theus/settings.json o .theus/settings.local.json), el diálogo lo señala para que sepas qué configuración del proyecto se activará al confiar.

Confiar en una carpeta desconocida equivale a autorizar que su configuración —MCP, hooks y permisos— se cargue. Revisa el contenido antes de aceptar si no reconoces el proyecto.

El API local: solo localhost, protegido por token

El servicio de inteligencia de proyecto de Theus (índice local, mapa neuronal y base de datos visual) expone un pequeño API HTTP. Por diseño, ese servidor escucha únicamente en la interfaz de loopback:

server.listen(requested, '127.0.0.1')

Solo se aceptan hosts de loopback (127.0.0.1, localhost, ::1); cualquier petición con otro Host u Origin se rechaza con forbidden_host. Además, todas las rutas del API exigen un token de sesión que se genera al arrancar. El token viaja en la URL del dashboard y se reenvía en cada petición, ya sea:

como parámetro de consulta ?token=…,
en la cabecera x-theus-token, o
como Authorization: Bearer ….

La comparación del token se hace en tiempo constante. Si falta o es inválido, el API responde que debe abrirse desde el dashboard o enviarse el token correcto. Puedes fijar el token con la variable de entorno THEUS_PROJECT_API_TOKEN en lugar de dejar que se genere aleatoriamente.

Cómo apagar o limitar el servicio local

El API local es opcional y controlable por variables de entorno:

Variable	Efecto
`THEUS_NO_PROJECT_INTELLIGENCE=1`	No arranca el índice local, el API ni el dashboard.
`THEUS_NO_PROJECT_SERVICES=1`	Desactiva los servicios de proyecto.
`THEUS_NO_OPEN_DASHBOARD=1`	Arranca el API sin abrir el navegador automáticamente.
`THEUS_PROJECT_API_TOKEN`	Fija el token de sesión del API local.

# Arrancar sin abrir el dashboard en el navegador
THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus

# Trabajar sin ningún servicio de inteligencia de proyecto
THEUS_NO_PROJECT_INTELLIGENCE=1 ./bin/theus --help

Buenas prácticas

Revisa antes de confiar. Solo pulsa "Sí, confío en esta carpeta" en proyectos cuyo contenido conoces o has inspeccionado.
Mantén los permisos ajustados. Usa reglas deny para bloquear operaciones peligrosas y reserva allow para patrones estrechos y seguros; deja el resto en ask.
Cuida el token del API. El token da acceso al dashboard local; no lo compartas ni lo publiques en enlaces. Si prefieres controlarlo, fíjalo con THEUS_PROJECT_API_TOKEN.
Apaga lo que no uses. Si no necesitas el índice ni el dashboard, arranca con THEUS_NO_PROJECT_INTELLIGENCE=1.
Protege ~/.theus/. Ahí viven tu configuración, tus proveedores y el conocimiento indexado del proyecto; trátalo como información sensible de tu máquina.
Confía solo en el loopback. El API nunca debe exponerse fuera de localhost; Theus ya lo impide, evita colocar proxies que lo publiquen en la red.

Theus — agente de código local-first y multimodelo · Hecho en Perú