Guía de inicio rápido de entornos autohospedados
Configure su primer entorno autohospedado: instale Claude Code, cree el entorno, inicie un runner y enrute una sesión hacia él.
Un entorno autohospedado ejecuta sesiones en la nube de Claude Code en infraestructura que opera su organización, ejecutadas por procesos runner que usted implementa. Este inicio rápido configura el primero, el más pequeño que funciona: un runner en un único host, ejecutando una sesión de prueba. Hay dos pasos: crear el entorno, iniciar un runner y enrutar una sesión hacia él, luego enviar un mensaje de seguimiento a esa sesión desde su terminal. Se moverá entre dos superficies: claude.ai para crear el entorno, verificar su estado y enrutar una sesión, y una terminal en el host para todo lo que hace el runner.
Al final tendrá un entorno en la página de administración Cloud environments, un runner consultando trabajo, y una sesión ejecutándose en su host. Antes de conectar repositorios reales o sistemas internos, trabaje a través de Implementar en producción, que cubre la postura de seguridad, control de egreso, credenciales de git y orquestación.
Requisitos previos
Organización y roles
El lado de claude.ai necesita:
- Allow self-hosted environments activado por un Owner en la página de administración Cloud environments; el botón New no aparece hasta que esté activado. Si no tiene el rol, alguien que lo tenga puede crear el entorno y entregarle su secreto; los pasos de runner y terminal en esta página no necesitan ningún rol de claude.ai, y donde un paso verifica el estado en la interfaz de administración, las propias líneas de registro del runner le dan la misma señal.
- Una conexión de GitHub para su organización, para que los desarrolladores puedan seleccionar repositorios cuando inicien sesiones.
Host y red
El host del runner necesita:
- Un host o contenedor Linux o macOS con HTTPS saliente a
api.anthropic.com, aclaude.aiy a los hosts de descarga a los que redirige para el paso de instalación a continuación, y a su host de git para el clon; la tabla de requisitos de red tiene la lista completa. Windows no se admite como host de runner; ejecute el runner en un contenedor Linux en su lugar. Las estaciones de trabajo de desarrolladores no se ven afectadas, ya que las sesiones se inician desde claude.ai en un navegador. - Un repositorio para la sesión de prueba: uno público, o uno que este host ya pueda clonar mediante su URL HTTPS sin que se le soliciten credenciales.
- Un reloj sincronizado con la hora real, por ejemplo con NTP. La autenticación falla cuando el reloj está más de cinco minutos desincronizado; consulte Troubleshooting.
Software en el host del runner
Instale en el host antes de comenzar:
- Claude Code v2.1.224 o posterior, con cualquiera de los métodos de instalación estándar. El runner es parte del binario
claudeestándar, y las versiones anteriores no reconocen el subcomandoself-hosted-runner. El canallatestdel instalador nativo predeterminado lleva cada versión tan pronto como se publica; el canalstable, el caskclaude-codede Homebrew, y los repositorios estables apt, dnf y apk se retrasan aproximadamente una semana. Para fijar la versión exacta que ejecuta su flota, consulte Instalar una versión específica. Para imágenes de contenedor, consulte el Dockerfile en Implementar en producción. - Git 2.24 o más reciente. Algunas opciones de git en la página de implementación necesitan versiones más recientes; Configurar git establece cada piso.
Confirme que el host está listo:
claude self-hosted-runner --help
Un host listo imprime el texto de uso del runner, listando banderas como --environment-secret-file. En versiones anteriores a 2.1.224, el comando imprime la salida general de claude --help en su lugar; actualice con claude update o reinstale desde el canal latest.
Configurar un entorno y runner
Usa la configuración guiada o los pasos manuales. La configuración guiada es un solo comando que inicia una sesión interactiva de Claude Code y te guía por el resto. Usa los pasos manuales en su lugar en un host donde no sea posible una sesión interactiva. Úsalos también cuando alguien con el rol Owner haya creado el entorno y te haya entregado su secreto, ya que la configuración guiada necesita un inicio de sesión de Owner.
Ejecutar la configuración guiada
La configuración guiada te acompaña en la creación del entorno en la interfaz de administración, inicia un runner local con el archivo secreto que guardes, confirma que el runner se registra y escribe una hoja de referencia rápida en ./runner-setup/CHEAT-SHEET.md. Antes de ejecutarla, confirma tu inicio de sesión y tu versión:
- Inicio de sesión: ejecútala en una máquina donde hayas iniciado sesión con
claude auth loginusando una cuenta que tenga un rol Owner. Con solo una clave de API o un proveedor de modelos de terceros, la sesión se inicia, pero sus verificaciones de organización fallan. - Versión: confirma que la verificación de versión pasó. En versiones anteriores a 2.1.224, el comando setup inicia una sesión de Claude con las palabras como prompt en lugar de la configuración guiada.
Para iniciar la configuración guiada, ejecuta el subcomando setup en tu shell y sigue las instrucciones:
claude self-hosted-runner setup
La configuración no inicia una sesión de prueba por sí misma: te indica que inicies una en claude.ai/code. El último paso de la configuración detiene el runner que inició. Si sales de la configuración antes de ese paso, el runner sigue ejecutándose. Para continuar después del último paso, vuelve a iniciar el runner en tu shell con el comando que aparece en ./runner-setup/CHEAT-SHEET.md y luego enruta una sesión al entorno.
Configurar manualmente
Crea el entorno en claude.ai, inicia el runner desde una terminal en el host y luego regresa a claude.ai para confirmar que el runner aparece y enrutar una sesión hacia él. Si alguien con el rol Owner ya creó el entorno y te entregó su secreto, empieza en el paso 2.
Crear un entorno
Vaya a la página Cloud environments en la configuración de administración. Bajo Self-hosted environments, seleccione New, nombre el entorno, y seleccione Create. En el segundo paso del asistente, seleccione Copy environment key para copiar el secreto del entorno, que la interfaz de administración etiqueta como una clave de entorno. claude.ai muestra el secreto una vez, y no puede recuperarlo más tarde; expira 365 días después de la creación. El ID ccpool_... del entorno permanece visible en su diálogo de detalle; lo necesitará para la verificación aud en verificación de token y para enviar sesiones de prueba desde CI.
Si pierdes el secreto o necesitas rotarlo, crea un nuevo secreto desde la pestaña Configuration del entorno, distribuye el nuevo secreto a tus runners y luego revoca el antiguo. Los runners que tengan un secreto revocado fallan en su siguiente sondeo autenticado y salen, registrando poll auth failed, y tu orquestador los reinicia con el nuevo secreto.
Iniciar un runner
Crea el directorio del secreto. Este comando y el siguiente usan /etc/claude, que necesita root, y el archivo secreto que crean solo puede leerlo el usuario que los ejecuta. Si el runner se ejecutará como otro usuario, sale con error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). En ese caso, ejecuta ambos comandos como el usuario del runner, con un directorio en el que ese usuario pueda escribir en lugar de /etc/claude, y pasa la misma ruta a --environment-secret-file. Funciona cualquier ruta que el proceso del runner pueda leer.
mkdir -p /etc/claude
Escriba el secreto del entorno en un archivo. El comando a continuación lee desde su terminal para que el secreto se mantenga fuera del historial de shell: pegue el valor que copió, presione Enter, luego Ctrl-D, y el umask del subshell hace que el archivo sea legible solo por su propietario.
(umask 077 && cat > /etc/claude/environment-secret)
Elija un directorio base, reemplazando <writable-dir> en el comando runner a continuación con una ruta absoluta que el runner pueda escribir o crear. El runner crea el directorio al inicio, luego verifica repositorios y crea directorios por sesión bajo él. Sin --base-dir usa /workspace, que solo funciona si ese directorio ya existe y es escribible o inicia el runner como root.
Si el runner no puede crear o escribir en la ruta, sale al inicio con un error nombrando el directorio en lugar de registrarse. Consulte Troubleshooting.
Luego inicia el runner con --environment-secret-file y --base-dir:
claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'
El runner registra Registered: runner_id=<runner-id> una vez que se ha registrado en tu entorno y luego comienza a sondear en busca de trabajo. Si el runner sale más tarde, reinícialo tú mismo. Consulta Si el runner sale para saber cuándo ocurre eso.
Verificar que el runner aparece
Regresa a la página Cloud environments. El estado de tu entorno cambia de No runners deployed a Healthy a los pocos segundos de que el runner se inicie; abre el entorno y selecciona Activity para ver el runner en sí. Si no tienes acceso a la página de administración, la línea Registered: runner_id=<runner-id> en el registro del runner del paso anterior te da la misma señal.
Enrutar una sesión al entorno
Inicia una sesión en claude.ai/code y selecciona tu entorno en el selector de entornos, donde los entornos autohospedados aparecen junto a los alojados por Anthropic. Como repositorio, elige el de los requisitos previos: un repositorio público o uno que este host ya pueda clonar. El runner clona con las credenciales de git que el host ya tenga.
El siguiente runner disponible toma la sesión en cola y registra Picked up session <session-id> junto con su recuento de sesiones activas y su capacidad, para que puedas confirmar desde la propia salida del runner qué host tomó la sesión. Observa cómo trabaja la sesión y lee las respuestas de Claude en claude.ai/code.
Si la sesión no empieza a trabajar, identifica lo que ves:
- La sesión permanece en cola: consulta Troubleshooting.
- La sesión no se inicia por un error de git: el error aparece en la sesión y en el registro del runner. Si incluye el mensaje de git
could not read Username forseguido de la URL de tu host de git, el runner no tenía credenciales HTTPS para ese host. Consulta Configurar git, que también cubre las opciones de credenciales para repositorios privados en producción.
Si el runner sale
Si el runner sale durante este inicio rápido, vuelve a iniciarlo con el mismo comando. El runner puede salir por sí solo:
- Sesiones terminadas: el registro muestra
[runner:exit] account workload drained — exiting. El runner sale por diseño una vez que terminan sus sesiones activas. Consulta Runner lifecycle. - Pérdida de contacto: el registro muestra una línea
[runner:fatal]conrunner record gone server-sideo conpoll auth failed. Si el runner pierde contacto con Anthropic durante un tiempo, por ejemplo porque el host entra en suspensión, puede salir la próxima vez que se comunique con Anthropic.
Un turno terminado no finaliza tu sesión de prueba. Después del primer turno, la sesión sigue conectada y el runner sigue activo, así que puedes enviar un mensaje de seguimiento a la sesión sin reiniciar primero el runner.
Para producción, implementa el runner bajo un orquestador que lo reinicie al salir y espere más tiempo entre reinicios cuando el runner siga saliendo justo después de iniciarse. Consulta Implementar en producción y Cuando el runner sale.
Enviar un mensaje de seguimiento a una sesión en ejecución
Una vez que una sesión se ejecuta en su entorno, envíele un seguimiento desde la CLI de claude en cualquier máquina donde haya iniciado sesión con claude auth login; el comando no necesita ejecutarse desde la máquina que inició la sesión. El comando publica un mensaje:
claude -p "your message" --cloud <session-id>
Para <session-id>, pasa el ID desnudo session_... o cse_... o la URL claude.ai/code de la sesión. Un envío exitoso imprime Sent to cloud session. con el ID de sesión y un enlace de vista. Las formas de ID aceptadas, la salida JSON y los requisitos de cuenta y política están en Enviar seguimientos desde la CLI, ya que el comando funciona igual contra sesiones alojadas por Anthropic.
Qué sigue
- Implementar en producción: endurezca la implementación, controle el egreso, configure credenciales de git, y ejecute la flota bajo Kubernetes o Compose
- Personalizar sesiones: scripts de envoltura, hooks de ciclo de vida, runners bajo demanda, servidores MCP, y permisos
- Probar de extremo a extremo: una prueba de humo de CI que envía una sesión y lee las respuestas de Claude