Configuración

La configuración del Agent se hace desde la propia interfaz del Agent, no editando archivos a mano. Esta página documenta qué opciones hay, dónde se guardan internamente, y cómo recuperarlas si necesitas clonar o migrar la configuración.

Configurar la conexión a Nexus

Es lo único que necesita configurarse para que el Agent funcione. Se hace en la pantalla “Conectar este equipo” la primera vez que abres el Agent:

• URL de Nexus — la URL de tu portal de tenant (ej. https://acme.nexus.zoansoftware.com).
• Machine Key — la clave generada al crear el agente desde el portal.

Ver Instalación en Windows → Conectar el Agent a Nexus para el procedimiento detallado.

Se requiere ejecutar como administrador

La pantalla de configuración (tanto el registro inicial como cualquier cambio posterior) solo funciona si el Agent se abre como administrador. Esto evita que un usuario sin privilegios cambie la conexión en una máquina compartida.

Si abres el Agent como usuario normal, los campos aparecen en modo solo lectura y el botón de guardar está deshabilitado, con una advertencia para reabrirlo como admin.

Reconfigurar después de la primera vez

Después del primer registro, puedes:

• Desconectar y volver a conectar — desde el footer de la pantalla principal hay un botón Desconectar que limpia la configuración y vuelve a la pantalla inicial.
• Cambiar de instancia — si quieres mover el Agent a un Nexus diferente (ej. de “Pruebas” a “Producción”), desconectalo y volvé a conectarlo con la nueva URL y Machine Key.
• Regenerar la Machine Key — si la pierdes o sospechas compromiso, desde el portal regeneras la clave del agente. La clave anterior queda invalidada inmediatamente. Después actualizas el Agent con la clave nueva.

Dónde se guarda la configuración

El Agent persiste la configuración en:

C:\ProgramData\Zoan\Agent\agente.json

Es un archivo JSON con esta estructura:

{
  "nexusUrl":      "https://acme.nexus.zoansoftware.com",
  "machineKey":    "85f33cc1-f019-f0c1-50f1-97...",
  "agentId":       "a1b2c3d4-5678-90ef-...",
  "environmentId": "e1f2g3h4-...",
  "logLevel":      "info"
}

No edites el archivo a mano

• El archivo se reescribe cada vez que cambias algo desde la UI — tus ediciones manuales se pierden.
• Si el formato JSON queda inválido, el Agent lo descarta y vuelve a la pantalla “Conectar este equipo”.
• La Machine Key está en texto plano. Si necesitas clonarla a otra máquina, trata el archivo como un secreto: permisos restrictivos y borrado seguro cuando ya no lo uses.

Nivel de log

Por defecto el Agent escribe logs con nivel info. Hay cuatro niveles disponibles:

Nivel	Qué registra
debug	Detalle máximo: cada bridge call, cada heartbeat, cada paso interno. Útil para diagnóstico — produce mucho volumen.
info	Eventos significativos: registro, ejecuciones iniciadas y terminadas, errores. Recomendado en producción.
warn	Solo advertencias y errores.
error	Solo errores.

Para cambiar el nivel, edita agente.json (con el Agent cerrado) y modifica "logLevel", o usa la opción Configuración avanzada desde el menú de la bandeja del sistema (próximamente).

Archivos relacionados

Otros directorios y archivos que el Agent usa:

C:\ProgramData\Zoan\
├── Agent\
│   ├── agente.json              ← configuración (la que ves arriba)
│   └── logs\
│       ├── service.log          ← logs del servicio Windows (modo desatendido)
│       └── ui.log               ← logs de la UI (modo atendido)
├── Packages\                    ← paquetes de actividades instalados (.zpkg)
│   ├── Zoan.Packages.Browser.1.0.0\
│   ├── Zoan.Packages.Excel.1.0.0\
│   └── ...
└── Automations\                 ← proyectos descargados de Nexus para ejecutar (.zoan)
    └── <execution-id>\

Variables de entorno (opcional)

Para casos especiales (ambientes CI/CD, contenedores, scripts de provisioning), el Agent puede leer la configuración desde variables de entorno en lugar de agente.json:

Variable	Equivalente JSON
ZOAN_NEXUS_URL	nexusUrl
ZOAN_MACHINE_KEY	machineKey
ZOAN_LOG_LEVEL	logLevel

Si las variables están seteadas al arrancar el Agent, tienen prioridad sobre el archivo. Útil para automatizar el provisioning de muchos agentes con una herramienta de configuración (Ansible, Group Policy, etc.).