Skip to main content
Los entornos autohospedados están en versión beta pública en planes Team y Enterprise y están deshabilitados de forma predeterminada. Consulte Disponibilidad y limitaciones para conocer la ruta de habilitación y qué está excluido.
Un entorno autohospedado ejecuta sesiones en la nube de Claude Code en la infraestructura que opera su organización. Una sesión en la nube es cualquier sesión que se ejecuta en algún lugar que no sea la máquina del desarrollador: los desarrolladores las inician desde claude.ai, las aplicaciones móviles y de escritorio, la terminal con claude --cloud, y rutinas programadas, y de forma predeterminada se ejecutan en la infraestructura de Anthropic. En un entorno autohospedado, esas mismas sesiones se ejecutan dentro de su red, y la experiencia del desarrollador es la misma excepto por las diferencias en Disponibilidad y limitaciones y los problemas conocidos de la página de implementación. Si su equipo no utiliza sesiones en la nube, no hay nada que configurar aquí: las sesiones en una terminal o IDE siempre se ejecutan en la máquina del desarrollador. Si desea ejecutar Claude Code en su propia máquina siempre activa e impulsarla desde otros dispositivos, use Control remoto, que también está disponible en planes Pro y Max. Cuando esté listo para configurar, vaya directamente al inicio rápido; para revisar primero la postura de seguridad, comience con Implementar en producción. El resto de esta página explica cómo funciona el autohospedaje y cuándo elegirlo.

​
Cómo funcionan los entornos autohospedados

El autohospedaje tiene tres partes:
  • Entorno: un destino nombrado al que se pueden enviar sesiones en la nube. Su organización crea entornos en la configuración de administrador de claude.ai, y cada uno agrupa un conjunto de ejecutores.
  • Ejecutor: un programa que se ejecuta en hosts dentro de su red. Los ejecutores ejecutan las sesiones; la idea es la misma que un ejecutor de CI autohospedado.
  • Sesión: una tarea de Claude Code que un desarrollador inició.
Cuando un desarrollador inicia una sesión en la nube, la interfaz de inicio de sesión muestra un selector de entorno que enumera los entornos alojados por Anthropic junto con los que su organización ha creado. Si elige el suyo, el plano de control de Anthropic coloca la sesión en la cola de su entorno, donde un ejecutor la reclama, clona el repositorio que el desarrollador eligió e inicia un proceso de Claude Code en su host para ejecutarlo. El ejecutor se autentica en su host de git con credenciales que usted configura; Configurar git cubre las opciones. Las sesiones alcanzan sus servicios internos desde dentro de su red, y su host de git de la misma manera cuando es interno; el tráfico a Anthropic, el sondeo de colas, el flujo de eventos de la sesión e inferencia de modelos, es HTTPS saliente a api.anthropic.com, con la breve lista de hosts adicionales que las sesiones pueden alcanzar en Requisitos de red. Anthropic nunca se conecta a su red.
Diagrama de arquitectura de un entorno autohospedado: el límite de su red contiene un ejecutor, dos procesos de sesión de Claude Code dentro de él, y su host de git, con api.anthropic.com afuera sosteniendo cola, flujo de sesión e inferencia. El ejecutor sondea la cola y alcanza el host de git, cada proceso de sesión abre sus propias conexiones de flujo, inferencia y git, y cada conexión es saliente desde su red, sin ninguna entrante.Diagrama de arquitectura de un entorno autohospedado: el límite de su red contiene un ejecutor, dos procesos de sesión de Claude Code dentro de él, y su host de git, con api.anthropic.com afuera sosteniendo cola, flujo de sesión e inferencia. El ejecutor sondea la cola y alcanza el host de git, cada proceso de sesión abre sus propias conexiones de flujo, inferencia y git, y cada conexión es saliente desde su red, sin ninguna entrante.
Los dos cuadros de Claude Code en el diagrama son procesos de sesión: un ejecutor ejecutando dos sesiones a la vez, hasta su capacidad configurada. Un ejecutor sirve a un propietario a la vez y se bloquea a ese propietario cuando reclama su primera sesión, por lo que el código extraído nunca se mezcla entre propietarios; Ciclo de vida del ejecutor cubre la regla. Puede iniciar ejecutores usted mismo y mantenerlos en ejecución, o ejecutar el orquestador de escalado automático, un segundo proceso que hospeda, que inicia ejecutores a medida que las sesiones se colan; cada ejecutor sale por su cuenta cuando su trabajo termina. De cualquier manera, configura el entorno una vez, y aparece en el selector en cada superficie compatible.

​
Disponibilidad y limitaciones

Verifique esto antes de planificar un despliegue:

​
Por qué autohospedar

La mayoría de los equipos se benefician mejor de los entornos alojados por Anthropic, que no requieren infraestructura para ejecutar o mantener. El autohospedaje es para equipos cuya red, herramientas o requisitos de cumplimiento requieren mantener la ejecución de sesiones en la infraestructura que controlan. Si ese es su caso, planifique la propiedad operativa que conlleva: construye y mantiene la imagen del ejecutor, opera la flota y controla su red. A cambio, el autohospedaje le proporciona acceso a la red, herramientas personalizadas y control de cumplimiento:
  • Acceso a la red: las sesiones se ejecutan dentro de su red y pueden alcanzar servicios internos, bases de datos y registros sin exponerlos a Internet público
  • Herramientas personalizadas: preinstale compiladores, SDK y CLI internos en su imagen de ejecutor para que cada sesión comience lista para compilar
  • Cumplimiento: los clones de repositorio y artefactos de compilación permanecen en la infraestructura que controla. El contenido de la sesión aún va a api.anthropic.com para inferencia de modelos.

​
Entornos, ejecutores y sesiones

Los entornos se administran en la página Entornos en la nube en la configuración de administrador de claude.ai; los ejecutores son procesos que inicia y administra en su propia infraestructura.

​
Conceptos clave

Estos términos aparecen en todas las páginas autohospedadas: En campos de API, reclamaciones de token y nombres de métricas, el entorno aparece como pool, y el ID del entorno es el pool_id. La referencia asigna los dos términos, incluidos los nombres de bandera pool deprecados. Un ejecutor sirve a un propietario a la vez. La primera sesión que un ejecutor recoge bloquea el ejecutor al propietario de esa sesión, y el ejecutor luego ejecuta sesiones solo para ese propietario, hasta una capacidad configurada. Quién es el propietario depende de cómo se inició la sesión:
  • Sesiones que inicia un usuario: el propietario es la cuenta de ese usuario.
  • Sesiones de canal de Claude Tag: Claude las ejecuta sin cuenta de usuario adjunta, por lo que el propietario es el agente de Claude Tag que inició la sesión. Cada sesión de canal que ese agente inicia tiene el mismo propietario, quienquiera que haya enviado el mensaje de Slack, por lo que un ejecutor bloqueado a él sirve sesiones que diferentes personas iniciaron cuando lo ejecuta en una --capacity superior a uno o con un --drain-grace-sec positivo. Un ejecutor bloqueado a un usuario nunca recoge estos, y un ejecutor bloqueado a un agente de Claude Tag nunca recoge sesiones de un usuario.
El tamaño mínimo de la flota es, por lo tanto, el número de propietarios que espera que estén activos a la vez, contando usuarios y agentes de Claude Tag.

​
Ciclo de vida de la sesión

Cuando un desarrollador inicia una sesión y selecciona su entorno, el plano de control de Anthropic coloca la sesión en la cola del entorno. Desde allí:
  1. Un ejecutor con capacidad libre reclama la sesión y mantiene un arrendamiento en ella.
  2. El ejecutor clona el repositorio en su directorio de trabajo e genera un proceso secundario de Claude Code.
  3. El secundario transmite eventos de vuelta sobre HTTPS mientras el ejecutor sigue sondeando; cada sondeo actualiza el arrendamiento y funciona como el latido del corazón.
  4. Si el ejecutor deja de sondear durante aproximadamente 60 segundos, el servidor vuelve a encolar la sesión para otro ejecutor.
El ejecutor da a cada solicitud de sondeo 10 segundos. Cuando una solicitud agota el tiempo de espera, se pierde o recibe una respuesta que el ejecutor no puede analizar, el ejecutor sigue sirviendo sus sesiones activas y reintenta después de un segundo o dos en lugar de esperar al siguiente sondeo programado. Por ejemplo, un proxy de interceptación que responde al sondeo con su propia página produce una respuesta que el ejecutor no puede analizar. Cada vez que otra solicitud falla de una de esas maneras, el ejecutor duplica la brecha antes del siguiente reintento, hasta 20 segundos, y acorta la brecha siempre que el arrendamiento esté cerca de expirar.

​
Ciclo de vida del ejecutor

La primera sesión que un ejecutor recoge bloquea el ejecutor al propietario de esa sesión, y el ejecutor ejecuta hasta --capacity sesiones concurrentes para ese propietario. Mientras el ejecutor tiene sesiones activas y no ha recibido una señal de apagado o alcanzado su tiempo de jubilación, el ejecutor sigue reclamando el trabajo en cola del propietario bloqueado. Lo que sucede una vez que terminan depende de --drain-grace-sec:
  • En el valor predeterminado de 0: el ejecutor sale tan pronto como sus sesiones activas terminan, sin sondear más, por lo que el orquestador en el que lo implementa, como Kubernetes, puede reiniciarlo con un disco fresco, listo para servir a cualquier propietario.
  • En un valor positivo: el ejecutor sigue sondeando la cola del propietario bloqueado durante esa cantidad de segundos antes de salir.
Este ciclo de vida aísla el código extraído de cada propietario sin requerir que el ejecutor elimine el estado del disco entre propietarios. La forma en que su infraestructura detiene un ejecutor decide si necesita --retire-at. Una eliminación que entrega SIGTERM no necesita bandera: el ejecutor drena como Tiempo de apagado describe, o sigue sirviendo las sesiones que ya tiene cuando establece --defer-shutdown-max-min. Si su infraestructura en su lugar destruye hosts en un tiempo de reloj de pared conocido sin una señal, o con un período de gracia demasiado corto para drenar, como un límite de vida útil de sandbox o reclamación de instancia spot, pase --retire-at <epoch-seconds> establecido a unos minutos antes de ese tiempo. En el tiempo de jubilación:
  1. El ejecutor deja de aceptar trabajo nuevo.
  2. El ejecutor libera cada sesión activa a través de la misma ruta de liberación que usa la bandera --release-idle-session-min, por lo que la sesión se reanuda en un ejecutor fresco cuando el usuario envía su siguiente mensaje. Cuándo el ejecutor libera cada sesión depende de su estado:
    • El ejecutor libera una sesión que está en medio de un turno tan pronto como ese turno termina.
    • Cuando un turno termina y deja tareas en segundo plano ejecutándose, el ejecutor espera hasta 60 segundos para ellas, luego libera la sesión incluso si aún se están ejecutando. Si las tareas han terminado pero el turno de seguimiento que lee sus resultados aún no se ha ejecutado, el ejecutor mantiene la sesión hasta que ese turno termina, y espera no más de SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS para que ese turno comience.
  3. El ejecutor sale 0 una vez que todas sus sesiones se liberan.
Un turno que sobrevive a la eliminación aún se pierde; Tiempo de apagado cubre el tamaño del margen. Sin --retire-at, una eliminación de host sin señal es indistinguible de un bloqueo: el plano de control registra un trabajador perdido en lugar de una liberación limpia, y la sesión se vuelve a encolar a otro ejecutor.

​
Rutas de red

El ejecutor y sus sesiones hacen varios tipos de conexión saliente, y no se requiere conectividad entrante desde Anthropic:
  • Plano de control: el ejecutor sondea api.anthropic.com para trabajo y publica eventos de progreso de configuración y falla, todo HTTPS saliente. El sondeo funciona como el latido del corazón del ejecutor.
  • Conector SCM: el orquestador opcional conector SCM tunnel es la única conexión WebSocket.
  • Git: el ejecutor clona desde y empuja a su host de git sobre HTTPS o SSH, autenticado con credenciales que su implementación proporciona; Configurar git cubre las opciones, incluidas credenciales acuñadas por sesión y el proxy de git de Anthropic, que enruta git a través de api.anthropic.com en su lugar.
  • Secundario de sesión: el proceso secundario de Claude Code mantiene el flujo de eventos de la sesión a api.anthropic.com, y realiza sus propias llamadas salientes para inferencia de modelos y para comandos de git ejecutados durante la sesión. Consulte Requisitos de red para la lista completa de salida. El diagrama anterior muestra estas rutas, aparte del conector SCM opcional.
La inferencia de modelos utiliza la API de Anthropic. El plano de control entrega el punto final de la API a cada sesión, y la sesión se autentica con un token OAuth emitido por Anthropic con alcance de sesión, por lo que la inferencia no se puede enrutar a través de Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, o una puerta de enlace LLM en entornos autohospedados. Los proxies de salida corporativos son compatibles. El ejecutor y el orquestador de escalado automático opcional honran el proxy y las variables de entorno mTLS descritas en Configuración de red, como HTTPS_PROXY y NO_PROXY; establézcalas en el entorno de cada proceso. Las variables cubren llamadas de plano de control, el WebSocket del conector SCM del orquestador, y el clon integrado para remotos HTTPS, y las sesiones las heredan del ejecutor. El flujo de sesión utiliza eventos enviados por servidor sobre HTTPS, por lo que un proxy en la ruta no debe almacenar en búfer respuestas. Si su proxy también requiere un encabezado Proxy-Authorization, el ejecutor puede agregarlo a cada conexión que abre al proxy; consulte Autenticarse en un proxy de salida.

​
Qué permanece en su infraestructura

Los clones de repositorio, artefactos de compilación, secretos y cualquier archivo que una sesión cree o modifique permanecen en las máquinas que aprovisiona. La conversación en sí, incluidas indicaciones, respuestas y resultados de herramientas, va a api.anthropic.com para inferencia de modelos, y Anthropic almacena la transcripción de la sesión para que pueda reanudar la sesión desde otra superficie compatible. Un entorno autohospedado mueve la ejecución de sesiones a su red. El plano de control sigue siendo alojado por Anthropic: la orquestación de sesiones, el encolamiento y la interfaz de claude.ai continúan ejecutándose en la infraestructura de Anthropic.

​
Empezar

Las páginas de entornos autohospedados se organizan por lo que está haciendo:
  • Inicio rápido: instale Claude Code, cree un entorno, inicie un ejecutor y enrute su primera sesión
  • Implementar en producción: endurecimiento de seguridad, salida de red, credenciales de git, recetas de Kubernetes y Compose, problemas conocidos y solución de problemas
  • Personalizar sesiones: scripts de contenedor para credenciales por sesión, hooks de ciclo de vida, ejecutores bajo demanda, servidores MCP y permisos
  • Prueba de extremo a extremo: una prueba de humo de CI que verifica una imagen de ejecutor antes de promoverla
  • Referencia: cada bandera de CLI, variable de entorno, métrica y el punto final de salud
  • Verificar identidad de sesión: valide el token de sesión desde sus propios servicios antes de otorgar acceso