> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instalación del Collector > Documentación de instalación del AgentEye Collector. El daemon `agenteye-collector` garantiza que la telemetría de tus agentes llegue a AgentEye sin bloquear nunca tu aplicación. Tu código escribe eventos en un directorio local y continúa su ejecución; el collector toma el control desde ese momento, subiendo cada archivo en milisegundos y sobreviviendo reinicios, interrupciones de red y errores transitorios del servidor. Las subidas fallidas se reintentan con retroceso exponencial, y un barrido periódico de recuperación vuelve a encolar cualquier archivo que haya quedado pendiente tras un fallo o despliegue. El resultado es una entrega durable y de tipo "lanzar y olvidar": tus agentes siguen funcionando a plena velocidad mientras el collector garantiza que ningún evento se pierda en tránsito. Mecánicamente, el collector es un daemon ligero que monitorea `$AGENTEYE_HOME/events/` (por defecto: `~/.agenteye/events/`) en busca de archivos `.jsonl` escritos por el SDK de Python y los sube al servidor de AgentEye. > **Cambio de nombre:** el comando del collector ahora es **`agenteye-collector`** (antes era `agenteye`). El nombre abreviado `agenteye` ahora pertenece al CLI de AgentEye. Si estás actualizando una instalación existente, consulta [enterprise-docs/collector-migration.md](/es/agenteye/collector-migration). *** ## Requisitos previos * Tu `AGENTEYE_TOKEN`: un PAT de GitHub que tú mismo generas (consulta [enterprise-docs/github-token.md](/es/agenteye/github-token)) * La URL del servidor y una clave de API del collector (consulta [enterprise-docs/api-keys.md](/es/agenteye/api-keys)) *** ## Opción A: Binario (recomendado) Hay binarios estáticos precompilados disponibles para Linux, macOS y Windows (x86\_64 y arm64). Descarga el binario para tu plataforma directamente desde el repositorio `agenteye-enterprise/releases`, bajo la etiqueta de lanzamiento más reciente `collector/v`. Nombres de artefactos disponibles: | Plataforma | Artefacto | | --------------- | --------------------------------------- | | Linux x86\_64 | `agenteye-collector-linux-x86_64` | | Linux arm64 | `agenteye-collector-linux-arm64` | | macOS x86\_64 | `agenteye-collector-darwin-x86_64` | | macOS arm64 | `agenteye-collector-darwin-arm64` | | Windows x86\_64 | `agenteye-collector-windows-x86_64.exe` | | Windows arm64 | `agenteye-collector-windows-arm64.exe` | **Descargar con el CLI `gh`** (reemplaza la versión y elige el artefacto de tu plataforma): ```bash theme={null} VERSION=0.0.1-beta.13 GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \ --repo agenteye-enterprise/releases \ --pattern 'agenteye-collector-linux-x86_64' chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` **O con `curl`:** ```bash theme={null} VERSION=0.0.1-beta.13 ARTIFACT=agenteye-collector-linux-x86_64 curl -fsSL \ -H "Authorization: token $AGENTEYE_TOKEN" \ -L "https://github.com/agenteye-enterprise/releases/releases/download/collector%2Fv${VERSION}/${ARTIFACT}" \ -o agenteye-collector chmod +x agenteye-collector sudo mv agenteye-collector /usr/local/bin/agenteye-collector ``` *** ## Opción B: Docker ```bash theme={null} echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/collector:beta-latest ``` > Las compilaciones beta actuales publican la etiqueta flotante `:beta-latest`; la etiqueta `:latest` solo se asigna a versiones estables. Para despliegues reproducibles, se recomienda usar una etiqueta de versión fija como `:v0.0.1-beta.13`. **Ejecutar:** ```bash theme={null} docker run -d --restart unless-stopped \ --name agenteye-collector \ -e AGENTEYE_URL=https://ingest.example.com/events \ -e AGENTEYE_KEY="$AGENTEYE_KEY" \ -e AGENTEYE_HOME=/data \ -v "$HOME/.agenteye:/data" \ ghcr.io/agenteye-enterprise/collector:beta-latest \ start ``` La imagen oficial se ejecuta como usuario no-root, por lo que debes definir `AGENTEYE_HOME` explícitamente y montar el directorio de cola del host en él. El montaje de volumen comparte el mismo directorio `~/.agenteye/` en el que el SDK de Python escribe en el host. Si ya tienes `AGENTEYE_HOME` configurado en otra ubicación del host, monta ese directorio en lugar de `$HOME/.agenteye`. *** ## Configuración Todas las opciones pueden establecerse de tres formas (de mayor a menor prioridad): 1. Bandera de CLI: `agenteye-collector start --url https://...` 2. Variable de entorno: `AGENTEYE_URL=https://...` 3. Archivo de configuración: `~/.agenteye/config.json` ### Opciones obligatorias | Opción | Bandera CLI | Variable de entorno | Clave en config.json | | --------------- | ------------- | ------------------- | -------------------- | | URL del backend | `--url ` | `AGENTEYE_URL` | `"url"` | | Clave de API | `--key ` | `AGENTEYE_KEY` | `"key"` | ### Opciones opcionales (con valores por defecto) | Opción | Bandera CLI | Variable de entorno | Clave en config.json | Por defecto | | --------------------------------------- | ------------------------------ | --------------------------------- | -------------------------- | ----------- | | Máx. subidas simultáneas | `--max-concurrent-uploads ` | `AGENTEYE_MAX_CONCURRENT_UPLOADS` | `"max_concurrent_uploads"` | `64` | | Intervalo del barrido (s) | `--sweep-interval ` | `AGENTEYE_SWEEP_INTERVAL` | `"sweep_interval_secs"` | `60` | | Edad mínima de archivo para barrido (s) | `--sweep-min-age ` | `AGENTEYE_SWEEP_MIN_AGE` | `"sweep_min_age_secs"` | `120` | | Máx. archivos por barrido | `--sweep-max-files ` | `AGENTEYE_SWEEP_MAX_FILES` | `"sweep_max_files"` | `64` | | Máx. intentos de subida | `--max-retries ` | `AGENTEYE_MAX_RETRIES` | `"max_retries"` | `5` | | Retardo base de reintento (ms) | `--retry-base-delay ` | `AGENTEYE_RETRY_BASE_DELAY` | `"retry_base_delay_ms"` | `1000` | ### Opciones mTLS (opcionales) Para despliegues que requieren TLS mutuo (mTLS), el collector puede presentar un certificado de cliente durante el protocolo de enlace TLS. Si no se configuran estas opciones, el collector utiliza HTTPS estándar. | Opción | Bandera CLI | Variable de entorno | Clave en config.json | | ---------------------------------- | ------------------- | ------------------- | -------------------- | | Certificado de cliente (PEM) | `--tls-cert ` | `AGENTEYE_TLS_CERT` | `"tls_cert"` | | Clave privada del cliente (PEM) | `--tls-key ` | `AGENTEYE_TLS_KEY` | `"tls_key"` | | Certificado CA personalizado (PEM) | `--tls-ca ` | `AGENTEYE_TLS_CA` | `"tls_ca"` | `--tls-cert` y `--tls-key` deben configurarse juntos. Los archivos deben estar codificados en PEM. `--tls-ca` es independiente y solo es necesario cuando el servidor de AgentEye presenta un certificado TLS que no ha sido emitido por una CA de confianza pública (por ejemplo, autofirmado por un emisor `cert-manager` dentro del clúster cuando no tienes un dominio DNS real). El collector añade la CA proporcionada como ancla de confianza adicional; las raíces públicas estándar siguen siendo de confianza, por lo que los despliegues existentes no se ven afectados. El archivo puede contener un único certificado PEM o una cadena completa (múltiples bloques PEM concatenados). **¿Ejecutas el collector como sidecar en tu pod de aplicación?** Consulta [enterprise-docs/single-pod-deployment.md](/es/agenteye/single-pod-deployment) para ver el patrón completo en EKS: paquete mTLS entregado mediante AWS Secrets Manager + Secrets Store CSI Driver + IRSA, con rotación automática. Cuando se ejecuta en Kubernetes con el patrón de transferencia de Secrets, monta el Secret del certificado como un volumen y apunta estas rutas a los archivos montados: ```yaml theme={null} # Ejemplo: fragmento de Deployment del collector volumes: - name: mtls-certs secret: secretName: agenteye-collector-mtls containers: - name: collector env: - name: AGENTEYE_TLS_CERT value: /etc/agenteye/tls/tls.crt - name: AGENTEYE_TLS_KEY value: /etc/agenteye/tls/tls.key # Solo cuando el certificado del servidor no es de confianza pública (por ejemplo, CA # autofirmada dentro del clúster). El mismo Secret normalmente incluye ca.crt junto # a tls.crt/tls.key. - name: AGENTEYE_TLS_CA value: /etc/agenteye/tls/ca.crt volumeMounts: - name: mtls-certs mountPath: /etc/agenteye/tls readOnly: true ``` ### Ejemplo de `~/.agenteye/config.json` ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "max_concurrent_uploads": 16, "sweep_interval_secs": 30 } ``` Con mTLS: ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key" } ``` Con mTLS más una CA personalizada (servidor AgentEye autofirmado): ```json theme={null} { "url": "https://ingest.example.com/events", "key": "sk-...", "tls_cert": "/etc/agenteye/tls/tls.crt", "tls_key": "/etc/agenteye/tls/tls.key", "tls_ca": "/etc/agenteye/tls/ca.crt" } ``` Si `AGENTEYE_HOME` está definido, se usará ese directorio en lugar de `~/.agenteye`. *** ## Configuración inicial Tras la instalación, configura el collector con la URL de tu servidor y la clave de API: ```bash theme={null} mkdir -p ~/.agenteye cat > ~/.agenteye/config.json <<'EOF' { "url": "https://ingest.example.com/events", "key": "YOUR_COLLECTOR_KEY" } EOF ``` > Usa `https` para cualquier despliegue que atraviese una red no confiable, de modo que los eventos no se envíen en texto plano. El formato en texto plano `http://your-server-host:8080/events` solo es apropiado para pruebas puramente locales contra un servidor en el mismo host. **Probar la conexión** (vaciado puntual, finaliza tras drenar los eventos pendientes): ```bash theme={null} agenteye-collector flush ``` `flush` reporta su progreso por stdout. Cuando la cola está vacía, imprime `No pending files.` y termina con código `0`. En caso contrario, imprime una línea por archivo (`[UPLOADED] ` o `[FAILED] ()`), seguida de un resumen `Done: / uploaded, failed.`. Esto convierte a `flush` en una verificación puntual muy práctica para comprobar que tu URL, clave y configuración TLS son correctos antes de iniciar el daemon. *** ## Ejecución como daemon ### Directamente ```bash theme={null} agenteye-collector start ``` ### Contenedor / Docker Cuando el collector y tu aplicación comparten un contenedor, ejecútalos bajo un supervisor de procesos. La opción más sencilla es `supervisord`; está disponible en todas las distribuciones principales, reinicia los procesos que fallen, reenvía señales y espera a un apagado controlado. **`Dockerfile`:** ```Dockerfile theme={null} FROM python:3.11-slim RUN apt-get update && apt-get install -y --no-install-recommends supervisor \ && rm -rf /var/lib/apt/lists/* # Obtener el binario agenteye-collector desde la imagen oficial. # Fija una etiqueta específica (:beta-latest para betas actuales, o :v); # :latest solo se publica para versiones estables. COPY --from=ghcr.io/agenteye-enterprise/collector:beta-latest \ /usr/local/bin/agenteye-collector /usr/local/bin/agenteye-collector COPY supervisord.conf /etc/supervisor/conf.d/agenteye.conf COPY my_agent.py /app/my_agent.py CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"] ``` **`supervisord.conf`:** ```ini theme={null} [supervisord] nodaemon=true user=root [program:agenteye-collector] command=/usr/local/bin/agenteye-collector start autorestart=true stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 [program:app] command=python /app/my_agent.py autorestart=unexpected stopwaitsecs=30 stdout_logfile=/dev/stdout stdout_logfile_maxbytes=0 stderr_logfile=/dev/stderr stderr_logfile_maxbytes=0 ``` Por qué estas configuraciones: * `autorestart=true` en agenteye-collector: reinicia ante cualquier salida (fallo, pánico, OOM). * `autorestart=unexpected` en la aplicación: solo reinicia en caso de salida con código distinto de cero, de modo que un agente puntual que termine con código 0 no entre en bucle. * `stopwaitsecs=30`: da al collector margen para drenar las subidas pendientes al recibir SIGTERM antes de que supervisord escale a SIGKILL. * `stdout_logfile=/dev/stdout`, `*_maxbytes=0`: redirige la salida de ambos programas al stdout del contenedor; sin archivos de log dentro del contenedor. Pasa `AGENTEYE_URL` / `AGENTEYE_KEY` (y cualquier variable de entorno TLS) con `docker run -e` como de costumbre; supervisord hereda el entorno. > **¿Contenedores separados?** Si ejecutas el collector en su propio contenedor (servicio de Docker Compose, sidecar de Kubernetes, etc.), no uses supervisord; la política de reinicio del runtime de contenedores ya se encarga de eso. Consulta [enterprise-docs/single-pod-deployment.md](/es/agenteye/single-pod-deployment) para ver el patrón de sidecar en EKS. **Sonda de liveness de Kubernetes** (aplica tanto si el collector se ejecuta solo como bajo supervisord): ```yaml theme={null} livenessProbe: exec: command: ["agenteye-collector", "health"] initialDelaySeconds: 10 periodSeconds: 30 ``` El daemon en ejecución escribe un latido en `$AGENTEYE_HOME/health.json` cada 30 segundos. `agenteye-collector health` lee ese archivo y termina con código `0` (saludable) solo cuando el latido es reciente y las tareas de subida se están ejecutando con normalidad; termina con código `1` (no saludable) cuando el latido tiene más de 90 segundos de antigüedad (por ejemplo, el daemon se ha detenido) o mientras el observador y el barredor se están reiniciando tras una salida inesperada. El latido solo es escrito por `start`, así que ejecuta la sonda contra el daemon de larga duración y no contra el comando puntual `flush`. ### systemd (Linux, recomendado para producción) ```ini theme={null} # /etc/systemd/system/agenteye-collector.service [Unit] Description=AgentEye Collector After=network.target [Service] ExecStart=/usr/local/bin/agenteye-collector start Restart=on-failure RestartSec=5 EnvironmentFile=/etc/agenteye/env [Install] WantedBy=multi-user.target ``` Crea `/etc/agenteye/env`: ``` AGENTEYE_URL=https://ingest.example.com/events AGENTEYE_KEY=YOUR_COLLECTOR_KEY ``` ```bash theme={null} sudo systemctl daemon-reload sudo systemctl enable --now agenteye-collector sudo systemctl status agenteye-collector ``` ### launchd (macOS) ```xml theme={null} Label ai.befailproof.agenteye-collector ProgramArguments /usr/local/bin/agenteye-collector start EnvironmentVariables AGENTEYE_URL https://ingest.example.com/events AGENTEYE_KEY YOUR_COLLECTOR_KEY RunAtLoad KeepAlive ``` ```bash theme={null} launchctl load ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist ``` *** ## Actualización del Collector El collector no se actualiza a sí mismo. Para actualizarlo: * **Binario:** descarga el nuevo artefacto `agenteye-collector--` desde la última versión `collector/v` (consulta [Opción A](#option-a-binary-recommended)), reemplaza `/usr/local/bin/agenteye-collector` y reinicia el servicio (`sudo systemctl restart agenteye-collector`, vuelve a ejecutar `launchctl load`, o reinicia tu supervisor). * **Docker:** ejecuta `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (o una etiqueta fija `:v`; `:latest` solo existe para versiones estables) y recrea el contenedor. `AGENTEYE_TOKEN` es necesario para descargar nuevos binarios/imágenes del repositorio de versiones privado, pero **no** es necesario para el daemon en ejecución. *** ## Subcomandos | Comando | Descripción | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agenteye-collector start` | Inicia el daemon de larga duración. Al arrancar, vacía cualquier evento que haya quedado de una ejecución anterior, luego monitorea nuevos archivos y los sube. El observador y el barredor se reinician automáticamente ante salidas inesperadas, y se escribe un latido en `health.json` cada 30 segundos. | | `agenteye-collector flush` | Puntual: sube todos los archivos pendientes y termina. Imprime `No pending files.` cuando la cola está vacía; en caso contrario, un registro `[UPLOADED]`/`[FAILED]` por archivo y un resumen `Done: / uploaded, failed.`. | | `agenteye-collector health` | Lee el latido `health.json` del daemon. Termina con código `0` cuando está reciente y saludable; termina con código `1` cuando el latido está desactualizado (más de 90s) o las tareas se están reiniciando. | *** ## Estructura de directorios ``` ~/.agenteye/ ├── config.json <- archivo de configuración opcional ├── events/ <- archivos .jsonl escritos por el SDK, recogidos por el collector └── failed/ <- archivos que fallaron todos los intentos de subida ``` Los archivos en `failed/` no se reintentan automáticamente. Para volver a ponerlos en cola manualmente, muévelos de nuevo a `events/` y ejecuta `agenteye-collector flush`.