Skip to main content
Los entornos autohospedados están en versión beta pública en planes Team y Enterprise; Disponibilidad y limitaciones cubre la ruta de habilitación. Esta página pone en marcha su primera sesión; consulte Entornos autohospedados para saber qué son y Implementar en producción para endurecimiento y recetas de flota.
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.
  • El conector de GitHub activado por un Owner, y la propia conexión de GitHub de cada desarrollador, para que puedan seleccionar repositorios de github.com 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, a claude.ai y 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. Una clave SSH por sí sola no es suficiente, porque el runner clona la URL https:// del repositorio. Para clonar mediante SSH en su lugar, consulta Reescribir URLs de git para redes privadas.
  • 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: Confirme que el host está listo:
Un host listo imprime el texto de uso del runner, listando flags como --environment-secret-file. En versiones anteriores a 2.1.224, el comando imprime la salida general de claude --help en su lugar. Si ves esa salida, actualiza Claude Code. Si ejecutas claude desde una imagen de contenedor, reconstruye la imagen con la versión 2.1.224 o posterior.

​
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 login usando 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:
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.
1

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.
2

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.
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.
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.
Usa un directorio dedicado al runner, no tu directorio home ni un directorio con tus propios clones. El runner trata lo que encuentre en <writable-dir>/<repo-owner>/<repo> como su propio clon, y puede restablecerlo y sobrescribir o eliminar archivos en él.
Si el runner no puede crear el directorio base o escribir en él, sale al iniciarse con un error que nombra el directorio en lugar de registrarse. Consulta Troubleshooting.Luego inicia el runner con --environment-secret-file y --base-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. Iniciado con este comando, sale por diseño después de atender una sesión, no después de cada turno. Para atender más sesiones, vuelve a iniciar el runner cada vez que salga. Consulta Si el runner sale para saber cuándo ocurre eso y qué registra el runner.
3

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.
4

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 mediante su URL HTTPS sin que se le pidan credenciales.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 Solución de problemas.
  • La sesión no se inicia por un error de git: si el error incluye el mensaje de git could not read Username for seguido de la URL de tu host de git, el runner no tenía credenciales HTTPS para ese host.
    • Proporcionar credenciales HTTPS: consulta Configurar git
    • Clonar por SSH en su lugar: si el host del runner ya tiene una clave SSH, consulta Reescribir URLs de git para redes privadas
    • Después de cualquiera de las dos soluciones: vuelve a iniciar el runner y observa la sesión fallida en lugar de iniciar una nueva. Si ha fallado varias veces, espera varios minutos a que el runner registre Picked up session.
    • Para usar otro repositorio en su lugar: archiva o elimina la sesión fallida, luego vuelve a iniciar el runner e inicia una sesión nueva. De lo contrario, el runner puede tomar la sesión fallida en lugar de la nueva.

​
Si el runner sale

Si el runner sale durante este inicio rápido, vuelve a iniciarlo. El runner puede salir por sí solo:
  • Nada en ejecución: el registro muestra [runner:exit] account workload drained — exiting. El runner sale por diseño una vez que ya no está ejecutando ninguna sesión, por ejemplo:
    • Archivaste o eliminaste la sesión: vuelve a iniciar el runner
    • La sesión no se pudo iniciar: corrige la causa y luego vuelve a iniciar el runner
  • Pérdida de contacto: el registro muestra una línea [runner:fatal] con runner record gone server-side o con poll 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:
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