Configuración de una máquina nueva dirigida por un agente

Esta página está escrita para un agente de codificación con IA (Claude Code, Codex, Hermes o similar) al que se le ha pedido configurar ADHDev en una máquina completamente nueva. Sigue los pasos numerados de abajo en orden y ejecuta cada comando exactamente como está escrito.

Para lectores humanos: puedes entregarle esta página a tu agente y decirle "configura ADHDev en esta máquina siguiendo la guía de máquina nueva" — el agente hará todo excepto el único inicio de sesión en el navegador que solo tú puedes aprobar.

El objetivo: partiendo de una máquina limpia, llegar a un daemon en ejecución y a un primer adhdev launch con la menor intervención humana posible. Exactamente un paso requiere una persona — el inicio de sesión en el navegador para Cloud — y está claramente marcado.

---

Elige primero un modo

ADHDev funciona en dos modos. Decide antes de empezar; el comando de instalación es idéntico, solo cambia el flujo de cuenta.

	A — Standalone	B — Cloud
Cuenta / inicio de sesión	Ninguna	GitHub o Google (inicio de sesión en el navegador)
¿Requiere un paso humano?	No — totalmente autónomo	Sí — una aprobación en el navegador
Panel	http://localhost:3000	https://adhf.dev
Ideal para	Una sola máquina, uso local, sin cuenta, configuración totalmente desatendida	Multimáquina, acceso remoto, compartir, Repo Mesh

Regla práctica para el agente: si el usuario no pidió funciones de nube/multimáquina/remotas, elige Standalone (A) — no necesita ninguna persona ni ninguna cuenta. Elige Cloud (B) solo cuando el usuario quiera explícitamente una cuenta, acceso remoto o mesh, y esté disponible para aprobar el inicio de sesión en el navegador.

---

Paso 1 — Comprueba los requisitos previos

ADHDev requiere Node.js ≥ 22.

node --version

• Node ≥ 22: perfecto, continúa.
• Sin Node, o Node < 22: el script de instalación (Paso 2) arrancará un runtime por ti (nvm/fnm/brew/apt/dnf/yum en macOS/Linux; un Node 22 portátil en Windows). Si prefieres instalar Node tú mismo primero, instala una 22.x LTS — no instales Node 24+ en Windows (ver la advertencia de abajo).

Windows + Node 24+

En Windows, un npm install -g adhdev global en Node.js 24+ está bloqueado. Usa el instalador de PowerShell en su lugar — aprovisiona un Node.js 22 portátil en ~/.adhdev/tools/node22 y lo usa. No intentes sortear esto forzando un Node más nuevo.

Aprovecha para verificar el sistema operativo y así elegir el comando de instalación correcto en el Paso 2: macOS, Linux o Windows.

---

Paso 2 — Instala la CLI (desatendido)

El script de instalación detecta la plataforma, instala Node.js si falta y pone adhdev en el PATH.

Para una configuración desatendida dirigida por un agente, define ADHDEV_NO_SETUP=1 para que el instalador solo instale y no lance el asistente de configuración interactivo (tú mismo conduces la configuración en los pasos posteriores).

macOS / Linux:

ADHDEV_NO_SETUP=1 curl -fsSL https://adhf.dev/install | sh

Windows (PowerShell):

$env:ADHDEV_NO_SETUP=1; iwr https://adhf.dev/install.ps1 -useb | iex

¿Ya tienes Node ≥ 22? (cualquier plataforma):

npm install -g adhdev

Homebrew (macOS / Linux) — no hace falta un Node aparte:

brew tap vilmire/adhdev && brew install adhdev

Homebrew incluye su propio runtime de Node.js. El script de instalación desatendida de arriba ya prefiere esta ruta automáticamente cuando brew está presente en macOS, así que normalmente no necesitas ejecutarlo a mano.

Opcional: canal preview

Define ADHDEV_CHANNEL=preview para instalar la build @next (release candidate) en lugar de la estable. Omítelo para la instalación estable normal. El tap de Homebrew sigue únicamente las versiones estables, así que las instalaciones de preview siempre pasan por npm.

Verifica la instalación:

adhdev --version

Esto debería imprimir un número de versión. El instalador actualiza el PATH para la sesión actual y lo registra de forma permanente, así que esto normalmente funciona de inmediato — no hace falta una terminal nueva.

Si aun así obtienes command not found (una shell restringida que no recogió el cambio de PATH), tienes dos alternativas que funcionan sin abrir una terminal nueva:

1. Invoca el shim estable por ruta completa (el instalador siempre deja adhdev aquí):

   # Windows
   & "$HOME\.adhdev\npm-global\adhdev.cmd" --version

   # macOS / Linux
   "$HOME/.adhdev/npm-global/bin/adhdev" --version

2. Vía de escape con el Node portátil de Windows — si el propio shim no se ejecuta (p. ej. la CLI aterrizó pero el PATH a node.exe está obsoleto), llama directamente al punto de entrada de la CLI instalada con el Node 22 portátil que aprovisionó el instalador:

   & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js" --version

Por lo demás, abrir una terminal nueva siempre funciona (el PATH queda registrado de forma permanente).

---

Paso 3 — Levanta el daemon

Modo A — Standalone (sin inicio de sesión)

Standalone no necesita cuenta. Arráncalo directamente:

adhdev standalone

Esto arranca el daemon en localhost:3847 y el panel en localhost:3000, sin autenticación. Sáltate el Paso 4 por completo — ve directamente al Paso 5.

Acceso opcional por LAN: adhdev standalone --host 0.0.0.0 --token <some-secret>. El --token es opcional y solo relevante para exponer standalone más allá de localhost.

Modo B — Cloud (requiere inicio de sesión)

Cloud necesita una cuenta. El inicio de sesión del Paso 4 es el único paso humano. No ejecutes adhdev daemon hasta que el Paso 4 informe que la máquina está online.

---

Paso 4 — Inicia sesión (solo Cloud) ⏸ PASO HUMANO

⏸ PASO HUMANO — el agente debe detenerse aquí

El inicio de sesión en Cloud usa un flujo de dispositivo OAuth que abre un navegador para que la persona lo apruebe. No existe ningún flag de inicio de sesión no interactivo, y es intencional — la autorización de cuenta es una frontera de seguridad que una persona cruza una vez, por diseño.

Nunca intentes saltarte esto inyectando un secreto de máquina a través de variables de entorno ni de ningún otro canal lateral. Eso no está soportado y no debe documentarse ni automatizarse.

Instrucciones para el agente en este paso:

1. No ejecutes tú mismo un comando de inicio de sesión y te quedes esperándolo. En su lugar, dile al usuario: "Necesito que inicies sesión. Ejecuta adhdev setup (alias adhdev login) y aprueba el aviso del navegador con tu cuenta de GitHub o Google."
2. Pausa y cede el control al usuario. No sigas mientras el inicio de sesión esté pendiente.
3. Reanuda solo cuando la cuenta esté autorizada. Sondea adhdev status y continúa al Paso 5 solo cuando informe que la máquina/cuenta está online. Hasta entonces, sigue esperando — no reintentes comandos de instalación ni del daemon.

Para la persona: ejecuta esto y aprueba la pestaña del navegador que se abre contra adhf.dev:

adhdev setup    # or: adhdev login

El inicio de sesión requiere un correo verificado de GitHub o Google, o será rechazado. Una vez que hayas aprobado en el navegador, devuélvele el control al agente.

Luego arranca el daemon de Cloud (en segundo plano, de larga vida):

adhdev daemon

El daemon se conecta a api.adhf.dev, registra la máquina e imprime un ID de máquina.

---

Paso 5 — Verifica

Confirma que el daemon está sano:

adhdev status

Esperado:

• Standalone: el daemon se reporta sano en localhost:3847.
• Cloud: la máquina aparece online, conectada a api.adhf.dev.

Si el estado no es sano, consulta la Resolución de problemas más abajo antes de lanzar nada.

---

Paso 6 — Lanza el primer agente

Lanza un agente CLI que el usuario ya tenga instalado:

adhdev launch claude    # Claude Code
# or:  adhdev launch codex-cli
# or:  adhdev launch <target>

adhdev launch <target> arranca el agente bajo el daemon y lo refleja en el panel. ADHDev no gestiona la clave de API ni el inicio de sesión propios del agente — cada herramienta mantiene su propia autenticación. Si el agente pide sus propias credenciales, eso se gestiona en la interfaz del agente, no en ADHDev.

Listo. Ahora tienes un daemon en ejecución, el panel conectado y un primer agente en vivo.

---

Resolución de problemas

• command not found: adhdev — el instalador también actualiza el PATH de la sesión actual, así que esto es raro. Si ocurre, invoca el shim estable por ruta completa en lugar de abrir una terminal nueva: & "$HOME\.adhdev\npm-global\adhdev.cmd" (Windows) o "$HOME/.adhdev/npm-global/bin/adhdev" (macOS/Linux). Último recurso solo en Windows si ni siquiera el shim se ejecuta: & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js". Abrir una terminal nueva también funciona — el PATH queda registrado de forma permanente.
• Node < 22 — instala una 22.x LTS (o deja que el instalador arranque una). ADHDev se niega a ejecutarse en Node más antiguo.
• Windows, la instalación falla en Node 24+ — usa el instalador de PowerShell (Node 22 portátil), no npm install -g en Node 24+.
• PSSecurityException en Windows / "cannot be loaded because running scripts is disabled" para ...\adhdev.ps1 — la política de ejecución Restricted por defecto bloquea el shim de PowerShell generado por npm (PowerShell prefiere adhdev.ps1 sobre adhdev.cmd). El instalador relaja esto automáticamente para el usuario actual; si quedó bloqueado (p. ej. por directiva de grupo) ejecuta tú mismo Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, o evita el .ps1 por completo llamando al .cmd: & "$HOME\.adhdev\npm-global\adhdev.cmd" --version.
• El daemon no se pone online (Cloud) — ejecuta adhdev status; si sigue offline, cierra sesión y vuelve a entrar: adhdev logout y luego adhdev setup, y después adhdev daemon de nuevo.
• El agente no responde tras el lanzamiento — adhdev status (¿daemon sano?), luego confirma que el proveedor está instalado para tu objetivo.

---

Script de bootstrap

Un script de Node complementario automatiza los Pasos 1–6 con la salvaguarda del paso humano ya incorporada: scripts/bootstrap-new-machine.mjs.

# See exactly what would run, without executing anything:
node scripts/bootstrap-new-machine.mjs --mode standalone --dry-run

# Fully unattended standalone setup:
node scripts/bootstrap-new-machine.mjs --mode standalone --yes

# Cloud: runs up to the sign-in, then stops and waits for you to approve in the browser:
node scripts/bootstrap-new-machine.mjs --mode cloud --yes

Flags:

• --mode cloud|standalone — qué modo configurar.
• --yes — desatendido; ejecuta la instalación/daemon sin confirmación adicional. Sin él, los pasos destructivos solo se describen, no se ejecutan.
• --dry-run — imprime solo los comandos; no ejecuta nada. Usa esto primero para previsualizar.

En modo cloud el script se detiene deliberadamente en el paso de inicio de sesión, imprime la instrucción de aprobación en el navegador y luego sondea adhdev status hasta que la máquina esté online antes de reanudar — reflejando el ⏸ PASO HUMANO de arriba. Nunca inyecta credenciales.