Astro 7.3.2 — Qué hace “por detrás” (telemetría, archivos, red y variables de entorno)

Documento de auditoría. Todo verificado directamente sobre el código instalado en /home/underghround/project/ts/node_modules/astro (versión 7.3.2) y sobre el paquete de telemetría @astrojs/telemetry@3.3.3. Fecha: 26 de septiembre de 2026. Máquina/usuario: underghround.

0. Punto de partida: npx astro telemetry disable

El comando astro telemetry disable ejecuta telemetry.setEnabled(false), que escribe en disco un archivo JSON global. No guarda ninguna variable de entorno (solo lee variables, nunca las escribe).

• Archivo: ~/.config/astro/config.json
• Contenido actual en esta máquina:

{
  "telemetry": {
    "enabled": false
  }
}

Otros valores posibles de ese archivo (cuando la telemetría se ha ejecutado al menos una vez):

{
  "telemetry": {
    "enabled": true,
    "notifiedAt": "1781873375772",
    "anonymousId": "1d6171b452a6cd2152530df4e1c4f74b1119fea793e8933540365513bee79404"
  }
}

• notifiedAt: timestamp del último aviso de telemetría mostrado.
• anonymousId: identificador persistente (hex aleatorio de 32 bytes), generado la primera vez que se usa Astro en ese home. Es un identificador por máquina/usuario, no por proyecto.

Mecanismo (en @astrojs/telemetry/dist/config.js)

• La ruta se calcula así:
  • Linux: ${XDG_CONFIG_HOME:-~/.config}/astro/config.json
  • macOS: ~/Library/Preferences/astro/config.json
  • Windows: %APPDATA%\astro\Config\config.json
• Escribe con fs.mkdirSync + fs.writeFileSync (síncrono, sin archivos temporales).
• astro telemetry reset borra el archivo completo con fs.rmSync.

Alcance: es GLOBAL, no por proyecto

En el constructor el nombre es fijo:

config = new GlobalConfig({ name: "astro" });

Por tanto todos los proyectos Astro del mismo usuario comparten el mismo config.json. Desactivar en un proyecto lo desactiva en todos; reactivar en cualquiera lo reactiva en todos.

¿PM2 lee el mismo archivo?

Sí, con la configuración actual:

• El daemon PM2 corre como underghround (pm2_home=/home/underghround/.pm2).
• HOME=/home/underghround y XDG_CONFIG_HOME no está definida.
• El ecosystem.config.cjs del proyecto no toca HOME ni XDG_CONFIG_HOME.

Matices que podrían cambiarlo:

1. Si PM2 se arranca como servicio (systemd/root u otro usuario) → distinto HOME → otro archivo.
2. PM2 hereda el entorno del daemon al arrancarlo. Si luego exportas XDG_CONFIG_HOME, los procesos ya lanzados mantienen el entorno viejo hasta pm2 kill.
3. env: { ... } del ecosystem solo afecta a ese proceso.

Nota importante: en producción PM2 ejecuta node dist/server/entry.mjs (servidor SSR), no el CLI. La telemetría se emite en comandos de CLI (astro build, astro dev), no en el runtime del servidor. Lo relevante es que el astro build de esa máquina respete el enabled: false global.

Cómo desactivarla de forma “portable” sin depender del archivo

Definir la variable de entorno ASTRO_TELEMETRY_DISABLED=1 (o TELEMETRY_DISABLED=1) en el entorno del proceso (CI, PM2, shell). Así la desactivación viaja con el proceso.

1. Archivos globales en ~/.config/astro/

Astro escribe más de un historial global distinto:

La ruta es la misma lógica en las 3 plataformas (XDG_CONFIG_HOME / APPDATA / ~/Library/Preferences). settings.json es el archivo de preferencias (SETTINGS_FILE = "settings.json" en dist/preferences/constants.js).

Preferencias (astro preferences)

Subcomandos disponibles: list, get, set, reset, enable, disable, delete.

Preferencias por defecto (dist/preferences/defaults.js):

{
  devToolbar: { enabled: true },      // Dev Overlay / barra de desarrollo
  checkUpdates: { enabled: true },    // Comprobación de actualizaciones
  _variables: { lastUpdateCheck: 0 }  // interno, no expuesto en CLI
}

• Hay dos ámbitos: proyecto (.astro/settings.json) y global (~/.config/astro/settings.json).
• get sin --global resuelve con esta prioridad: proyecto → global → defaults.
• set por defecto escribe en el proyecto; con --global escribe en el global.

2. Archivos por proyecto en .astro/

Se generan solos. .astro/ está en .gitignore del proyecto.

En build el data-store se escribe en config.cacheDir en lugar de .astro/. El comando astro sync regenera todo el tipado y la caché.

Ejemplo real de .astro/dev.json encontrado (servidor ya muerto):

{
  "pid": 186769,
  "port": 4321,
  "url": "http://localhost:4321",
  "urls": {
    "local": ["http://localhost:4321/"],
    "network": [],
    "networkInterfaceNames": []
  },
  "background": false,
  "startedAt": "2026-09-25T00:00:22.569Z"
}

3. Llamadas de red “ocultas”

Detalle del update check (dist/core/dev/update-check.js):

return (
  timeSinceLastCheck > CHECK_MS_INTERVAL &&
  process.env.ASTRO_DISABLE_UPDATE_CHECK !== "true" &&
  hasCheckUpdatesEnabled
);

4. Variables de entorno que Astro lee (ninguna la escribe)

Encontradas en node_modules/astro/dist:

5. Detección de agentes IA (am-i-vibing)

Astro 7.3.2 incluye una detección de “entorno agéntico” (si lo ejecuta un agente IA tipo OpenCode, Cursor, etc.) mediante el paquete am-i-vibing:

• Telemetría (dist/events/session.js): si detecta agente, añade al payload isAgentic: true y, si existen, agentId, agentName, agentType.
• CLI (dist/cli/dev/index.js y dist/cli/preview/index.js):

const agentDetected = !process.env.ASTRO_DEV_BACKGROUND && isRunByAgent();

Esto hace que dev/preview arranquen en background automáticamente cuando los lanza un agente.

6. Qué envía la telemetría si está activa

Payload (@astrojs/telemetry/dist/index.js):

• anonymousId — hex aleatorio persistente por usuario.
• anonymousSessionId — hex aleatorio por sesión.
• anonymousProjectId — hash del cwd (o del commit raíz de git si existe).
• Info de sistema (getSystemInfo): versión de Node, versión de Vite/Astro, plataforma, release, arquitectura, número/modelo/velocidad de CPU, memoria total, isDocker, isTTY, isWSL.
• Package manager y su versión.
• Config anonimizada: output, scopedStyleStrategy, trailingSlash, adapter, integrations.
• Comando CLI usado y sus flags (eventCliSession).
• En CI, el anonymousId se reemplaza por CI.<nombre CI>.

Nunca se envía el contenido de tus archivos ni tu código; sí la “forma” de tu configuración.

7. Otros comandos CLI poco visibles

Listados en dist/cli/index.js:

help, version, info, create-key, docs, telemetry, sync, preferences, add, dev, build, preview, check.

Destacan por poco conocidos: telemetry, preferences, info, docs, add, create-key.

8. Cómo auditarlo en vivo (sin enviar nada)

astro preferences list --json
astro info
DEBUG=astro:telemetry npx astro <comando>   # imprime el payload pero NO lo envía
npx astro telemetry disable                 # desactivar
npx astro telemetry reset                   # borrar config global (regenera anonymousId al usarse)

9. Resumen ejecutivo

1. astro telemetry disable escribe ~/.config/astro/config.json (global, compartido por todos los proyectos del usuario); no crea variables de entorno.
2. Astro escribe además ~/.config/astro/settings.json (preferencias globales) y .astro/* por proyecto.
3. Hace red en: telemetría, update check (~cada 12 días), astro add, astro docs.
4. Solo lee variables de entorno; nunca las persiste.
5. Detecta si lo ejecuta un agente IA (am-i-vibing) y lo reporta en telemetría + auto-background.
6. Desactivación robusta y portable: ASTRO_TELEMETRY_DISABLED=1 + ASTRO_DISABLE_UPDATE_CHECK=true (o astro preferences disable checkUpdates).