Guía de configuración de AgentVera Runner

Qué hace Runner

Usa Runner cuando quieras que los agentes se ejecuten en un servidor potente y siempre encendido en lugar de en tu portátil. Runner mantiene las sesiones de terminal de los agentes en ese servidor; cierra la tapa, pierde la conexión o conéctate desde otro ordenador y la sesión sigue.

• El código y las conversaciones se quedan en tu servidor.
• La conexión se retransmite a través del servidor de AgentVera mediante TLS cifrado; el tráfico de terminal retransmitido no se interpreta, ni se registra ni se almacena allí.
• Ves el uso de CPU, memoria y disco del servidor, las sesiones abiertas y los archivos de las carpetas que permitas.
• En las tareas que llegan por webhooks o con “Send to agent” en la web, el final de la salida del agente (hasta 6000 caracteres) se comunica al servidor como resumen de la tarea cuando termina su turno.

Requisitos

• Un servidor u ordenador con Linux o macOS.
• Node.js 20 o posterior, y npm.
• curl o wget.
• Para las sesiones de agente, una CLI instalada y con la sesión iniciada en ese servidor: Claude Code, Codex, Gemini CLI u opencode. Las sesiones de terminal siempre funcionan.
• Una organización de AgentVera con el plan Pro o Team.

Si falta Node.js, instálalo desde nodejs.org o con fnm:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

Para instalar Claude Code e iniciar sesión una vez:

npm install -g @anthropic-ai/claude-code
claude login

Instalación

1. Abre app.agentvera.dev/runners en tu navegador y haz clic en “Yeni runner ekle” (añadir un runner). Aparece un código de vinculación de 8 caracteres, válido durante 10 minutos.
2. Ejecuta el comando siguiente en tu servidor, sustituyendo KOD por tu código de vinculación.
3. En unos segundos el runner aparece como conectado en /runners. Ábrelo para ver el uso de CPU, memoria y disco e iniciar una sesión de Claude, Codex o de terminal con “Yeni ajan” (nuevo agente).

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD

Si el código de vinculación ha caducado, crea uno nuevo en /runners.

Opciones del instalador

Añade estas opciones al comando de instalación:

• --name NAME: el nombre del runner. Por defecto, el nombre de host de la máquina.
• --server URL: el servidor de AgentVera. Por defecto, https://app.agentvera.dev.
• --no-service: no instala un servicio en segundo plano, si solo vas a usar el runner desde la app de escritorio por SSH.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD --name build-server

Qué hace el instalador

• Instala Runner en ~/.agentvera-runner/app (una carpeta que solo tú puedes abrir) y enlaza el comando como ~/.local/bin/agentvera-runner.
• En Linux con systemd, crea un servicio de usuario llamado agentvera-runner que se reinicia solo si se detiene.
• Sin systemd, Runner se inicia en segundo plano y escribe su registro en ~/.agentvera-runner/runner.log; tras reiniciar el servidor, lo vuelves a iniciar a mano.
• En macOS, instala un agente launchd llamado dev.agentvera.runner que se inicia al iniciar sesión, se reinicia si se detiene y escribe su registro en ~/.agentvera-runner/runner.log.
• Guarda el token de acceso en un archivo que solo tú puedes leer.

En Linux, para que Runner siga en marcha después de cerrar sesión, ejecuta esto una vez:

sudo loginctl enable-linger $USER

Línea de comandos

agentvera-runner status               # version, service, pairing, server and allowed folders
agentvera-runner roots ~/projects      # limit agents and file access to these folders
agentvera-runner pair KOD --name NAME  # pair again
agentvera-runner daemon                # run Runner in the foreground

Sin roots, los agentes trabajan en tu carpeta personal. Tras volver a vincular, reinicia el servicio; Runner se conecta al arrancar.

Gestionar el servicio

Linux (systemd):

systemctl --user status agentvera-runner
systemctl --user restart agentvera-runner
systemctl --user stop agentvera-runner
journalctl --user -u agentvera-runner -f

macOS (launchd):

launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist   # stop
launchctl load -w ~/Library/LaunchAgents/dev.agentvera.runner.plist   # start
tail -f ~/.agentvera-runner/runner.log

Conectarse desde la app de escritorio

La página Runner de la app de escritorio de AgentVera se conecta a los runners de dos maneras: a través de la nube con la misma cuenta, o directamente por un servidor SSH guardado. Si vas a usar SSH, puedes instalar con --no-service; la app inicia Runner por sí misma al conectarse.

Desinstalar

1. Elimina el runner en app.agentvera.dev/runners. Su token se revoca de inmediato y deja de reconectarse.
2. Detén y elimina el servicio.
3. Borra los archivos de Runner.

# Linux
systemctl --user disable --now agentvera-runner
rm ~/.config/systemd/user/agentvera-runner.service

# macOS
launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist
rm ~/Library/LaunchAgents/dev.agentvera.runner.plist

# both
rm -rf ~/.agentvera-runner ~/.local/bin/agentvera-runner

Seguridad

• Runner solo abre conexiones salientes; no necesitas abrir puertos ni cambiar el cortafuegos.
• Solo los miembros activos de tu organización pueden ver el runner y conectarse a él. El personal de soporte que ve la cuenta como un usuario no puede conectarse.
• Las conexiones abiertas se cierran para los usuarios cuya pertenencia termina o cuya organización se suspende.
• Usa roots para decidir a qué carpetas se limitan los agentes y el acceso a archivos.
• Las tareas lanzadas por webhooks pueden enviar prompts al runner; conecta solo fuentes de confianza.

Solución de problemas

• “Node.js 20 ya da üstü gerekli” (se requiere Node.js 20 o posterior): instala Node.js 22 y vuelve a ejecutar el comando.
• Código de vinculación no válido: puede que hayan pasado los 10 minutos; obtén un código nuevo en /runners.
• Runner no aparece como conectado: revisa la salida de agentvera-runner status y los registros; comprueba que el servidor llega a app.agentvera.dev:443.
• Falta un tipo de agente en “Yeni ajan”: instala esa CLI en el servidor e inicia sesión; Runner solo muestra los agentes que encuentra instalados.