Skip to main content
Самостоятельно размещаемые окружения находятся в публичной бета-версии на планах Team и Enterprise; Доступность и ограничения охватывает путь включения. На этой странице вы запустите свой первый сеанс; см. Самостоятельно размещаемые окружения для понимания того, что это такое, и Развёртывание в production для укрепления и рецептов флота.
Самостоятельно размещаемое окружение запускает облачные сеансы Claude Code на инфраструктуре, которой управляет ваша организация, выполняемые процессами runner, которые вы развёртываете. Этот быстрый старт настраивает ваше первое окружение, самое маленькое из работающих: один runner на одном хосте, запускающий один тестовый сеанс. Есть два шага: создайте окружение, запустите runner и маршрутизируйте сеанс на него, затем отправьте сообщение этому сеансу из вашего терминала. Вы будете переключаться между двумя интерфейсами: claude.ai для создания окружения, проверки его статуса и маршрутизации сеанса, и терминалом на хосте для всего, что делает runner. К концу у вас будет окружение на странице администратора Cloud environments, runner, опрашивающий работу, и сеанс, работающий на вашем хосте. Прежде чем подключать реальные репозитории или внутренние системы, пройдите Развёртывание в production, которое охватывает позицию безопасности, контроль исходящего трафика, учётные данные git и оркестрацию.

​
Предварительные требования

​
Организация и роли

Для claude.ai требуется:
  • Allow self-hosted environments включено Владельцем на странице администратора Cloud environments; кнопка New не появляется, пока это не будет сделано. Если у вас нет этой роли, кто-то, кто её имеет, может создать окружение и передать вам его секрет; шаги runner и terminal на этой странице не требуют роли claude.ai, и там, где шаг проверяет статус в интерфейсе администратора, собственные строки логов runner дают вам тот же сигнал.
  • Коннектор GitHub, включённый пользователем с ролью Owner, и собственное подключение GitHub каждого разработчика, чтобы они могли выбирать репозитории github.com при запуске сессий.

​
Хост и сеть

Хост runner требует:
  • Хост или контейнер Linux или macOS с исходящим HTTPS к api.anthropic.com, к claude.ai и хостам загрузки, на которые он перенаправляет для шага установки ниже, и к вашему git-хосту для клонирования; таблица требований к сети содержит полный список. Windows не поддерживается в качестве хоста runner; запустите runner в контейнере Linux вместо этого. Рабочие станции разработчиков не затронуты, так как сеансы запускаются из claude.ai в браузере.
  • Репозиторий для тестовой сессии: публичный или такой, который этот хост уже может клонировать по его HTTPS URL без запроса учётных данных. Одного SSH-ключа недостаточно, поскольку runner клонирует https:// URL репозитория. Чтобы вместо этого клонировать по SSH, см. Rewrite git URLs for private networks.
  • Часы, синхронизированные с реальным временем, например с помощью NTP. Аутентификация не удаётся, когда часы отстают или спешат более чем на пять минут; см. Troubleshooting.

​
Программное обеспечение на хосте runner

Установите на хост перед началом:
  • Claude Code v2.1.224 или позже, с любым из стандартных методов установки. Runner является частью стандартного бинарного файла claude, и более ранние версии не распознают подкоманду self-hosted-runner. Runner, обслуживающему сессии Claude Tag, требуется v2.1.229 или позже и python3 в его PATH, поскольку хуки, предоставляемые control plane для этих сессий, запускают python3. Чтобы зафиксировать точную версию, которую запускает ваш парк, см. Install a specific version. Для образов контейнеров см. Dockerfile в Deploy to production.
  • Git 2.24 или новее. Некоторые опции git на странице развёртывания требуют более новых версий; Configure git указывает каждый минимум.
Подтвердите, что хост готов:
Готовый хост выводит текст использования runner, перечисляя флаги такие как --environment-secret-file. На версиях старше 2.1.224 команда выводит вместо этого общий вывод claude --help. Если вы видите этот вывод, обновите Claude Code. Если вы запускаете claude из образа контейнера, пересоберите образ с версией 2.1.224 или новее.

​
Настройка окружения и runner

Используйте либо пошаговую настройку, либо ручные шаги. Пошаговая настройка — это одна команда, которая запускает интерактивную сессию Claude Code и проводит вас через остальные действия. Используйте вместо неё ручные шаги на хосте, где интерактивная сессия невозможна. Также используйте их, если окружение создал пользователь с ролью Owner и передал вам его секрет, поскольку для пошаговой настройки требуется вход с ролью Owner.

​
Запуск пошаговой настройки

Пошаговая настройка проводит вас через создание окружения в админ-интерфейсе, запускает локальный runner с файлом секрета, который вы сохраняете, подтверждает, что runner регистрируется, и записывает шпаргалку в ./runner-setup/CHEAT-SHEET.md. Перед запуском проверьте вход и версию:
  • Вход: запускайте её на машине, где вы вошли с помощью claude auth login, используя учётную запись с ролью Owner. Если используется только API-ключ или сторонний поставщик моделей, сессия запустится, но проверки организации завершатся неудачей.
  • Версия: убедитесь, что проверка версии пройдена. На версиях старше 2.1.224 команда setup запускает сессию Claude с этими словами в качестве промпта вместо пошаговой настройки.
Чтобы запустить пошаговую настройку, выполните подкоманду setup в оболочке и следуйте инструкциям:
Пошаговая настройка сама не запускает тестовую сессию: она предлагает вам запустить её на claude.ai/code. Последний шаг настройки останавливает запущенный ею runner. Если вы выйдете из настройки до этого шага, runner продолжит работать. Чтобы продолжить после последнего шага, снова запустите runner в оболочке с помощью команды из ./runner-setup/CHEAT-SHEET.md, затем направьте сессию в окружение.

​
Ручная настройка

Создайте окружение на claude.ai, запустите runner из терминала на хосте, затем вернитесь на claude.ai, чтобы убедиться, что runner появился, и направить на него сессию. Если пользователь с ролью Owner уже создал окружение и передал вам его секрет, начните с шага 2.
1

Создайте окружение

Перейдите на страницу Cloud environments в параметрах администратора. В разделе Self-hosted environments выберите New, назовите окружение и выберите Create. На втором шаге мастера выберите Copy environment key, чтобы скопировать секрет окружения, который админ-интерфейс обозначает как ключ окружения. claude.ai показывает секрет один раз, и вы не можете получить его позже; он истекает через 365 дней после создания. ID окружения ccpool_... остаётся видимым в его диалоговом окне деталей; вам понадобится он для проверки aud в проверке токена и для отправки тестовых сеансов из CI.Если вы потеряли секрет или вам нужно его ротировать, создайте новый секрет на вкладке Configuration окружения, разверните новый секрет на ваших runners, затем отзовите старый. Runners с отозванным секретом не пройдут следующий аутентифицированный опрос и завершатся, записав в лог poll auth failed, а ваш оркестратор перезапустит их с новым секретом.
2

Запустите runner

Создайте директорию для секрета. Эта и следующая команды используют /etc/claude, что требует root, а создаваемый ими файл секрета доступен для чтения только пользователю, который их выполнил. Если runner будет работать от имени другого пользователя, он завершится с ошибкой error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). В этом случае выполните обе команды от имени пользователя runner, указав вместо /etc/claude директорию, в которую этот пользователь может записывать, и передайте тот же путь в --environment-secret-file. Подойдёт любой путь, который процесс runner может читать.
Запишите секрет окружения в файл. Команда ниже читает из вашего терминала, поэтому секрет остаётся вне истории shell: вставьте значение, которое вы скопировали, нажмите Enter, затем Ctrl-D, и umask подоболочки делает файл читаемым только его владельцем.
Выберите базовую директорию, заменив <writable-dir> в команде runner ниже абсолютным путём, который runner может писать или создавать. Runner создаёт директорию при запуске, затем проверяет репозитории и создаёт директории для каждого сеанса под ней. Без --base-dir он использует /workspace, что работает только если эта директория уже существует и доступна для записи или вы запускаете runner как root.
Используйте каталог, выделенный для runner, а не ваш домашний каталог или каталог с вашими собственными клонами. Runner считает всё, что находит в <writable-dir>/<repo-owner>/<repo>, своим клоном и может сбросить его, а также перезаписать или удалить в нём файлы.
Если runner не может создать базовый каталог или записывать в него, он завершается при запуске с ошибкой, в которой указан этот каталог, вместо регистрации. См. Устранение неполадок.Затем запустите runner с --environment-secret-file и --base-dir:
После регистрации в вашем окружении runner записывает в лог Registered: runner_id=<runner-id>, а затем начинает опрашивать наличие работы. Запущенный этой командой, он по задумке завершается после обслуживания одной сессии, а не после каждого хода. Чтобы обслуживать больше сессий, запускайте runner снова каждый раз, когда он завершается. О том, когда это происходит и что runner записывает в лог, см. Если runner завершился.
3

Проверьте, что runner появился

Вернитесь на страницу Cloud environments. Статус вашего окружения изменится с No runners deployed на Healthy в течение нескольких секунд после запуска runner; откройте окружение и выберите Activity, чтобы увидеть сам runner. Если у вас нет доступа к странице администратора, тот же сигнал даёт строка Registered: runner_id=<runner-id> в логе runner из предыдущего шага.
4

Направьте сессию в окружение

Запустите сессию на claude.ai/code и выберите ваше окружение в средстве выбора окружения, где самостоятельно размещаемые окружения отображаются рядом с размещаемыми Anthropic. В качестве репозитория выберите указанный в предварительных требованиях: публичный репозиторий или тот, который этот хост уже может клонировать по его HTTPS URL без запроса учётных данных.Следующий доступный runner подхватывает поставленную в очередь сессию и записывает в лог Picked up session <session-id> вместе с числом активных сессий и ёмкостью, поэтому по собственному выводу runner можно определить, какой хост взял сессию. Наблюдайте за работой сессии и читайте ответы Claude на claude.ai/code.Если сессия не начинает работу, сопоставьте то, что вы видите:
  • Сессия остаётся в очереди: см. Устранение неполадок.
  • Сессия не запускается из-за ошибки git: если ошибка содержит could not read Username for из git, за которым следует URL вашего git-хоста, у runner не было учётных данных HTTPS для этого хоста.
    • Предоставьте учётные данные HTTPS: см. Настройка git
    • Клонируйте через SSH: если на хосте runner уже есть SSH-ключ, см. Перезапись git URL для частных сетей
    • После любого из этих исправлений: снова запустите runner и следите за неудавшейся сессией, а не запускайте новую. Если она уже завершилась неудачей несколько раз, подождите несколько минут, пока runner не запишет в лог Picked up session.
    • Чтобы вместо этого использовать другой репозиторий: архивируйте или удалите неудавшуюся сессию, затем снова запустите runner и начните новую сессию. Иначе runner может подхватить неудавшуюся сессию вместо новой.

​
Если runner завершился

Если runner завершится во время этого быстрого старта, запустите его снова. Runner может завершиться самостоятельно:
  • Ничего не выполняется: в логе отображается [runner:exit] account workload drained — exiting. Runner по задумке завершается, как только перестаёт выполнять какую-либо сессию, например:
    • Вы архивировали или удалили сессию: запустите runner снова
    • Сессия не запустилась: устраните причину, затем запустите runner снова
  • Потеряна связь: в логе отображается строка [runner:fatal] с runner record gone server-side или с poll auth failed. Если runner на некоторое время теряет связь с Anthropic, например потому что хост перешёл в спящий режим, он может завершиться при следующем обращении к Anthropic.
Завершённый ход не завершает вашу тестовую сессию. После первого хода сессия остаётся подключённой, а runner продолжает работать, поэтому вы можете отправить сессии следующее сообщение, не перезапуская runner. Для production развёртывайте runner под оркестратором, который перезапускает его при завершении и увеличивает паузу между перезапусками, если runner продолжает завершаться сразу после запуска. См. Deploy to production и When the runner exits.

​
Отправьте follow-up сообщение работающему сеансу

Когда сеанс работает на вашем окружении, отправьте ему follow-up из CLI claude на любой машине, где вы вошли с помощью claude auth login; команда не должна запускаться с машины, которая запустила сеанс. Команда отправляет одно сообщение:
Для <session-id> передайте голый ID session_... или cse_... или URL сессии claude.ai/code. Успешная отправка выводит Sent to cloud session. с ID сессии и ссылкой для просмотра. Допустимые формы ID, вывод JSON, а также требования к учётной записи и политикам описаны в разделе Отправка follow-up сообщений из CLI, так как команда работает одинаково и с сессиями, размещёнными Anthropic.

​
Что дальше

  • Развёртывание в production: укрепите развёртывание, контролируйте исходящий трафик, настройте учётные данные git и запустите флот под Kubernetes или Compose
  • Customize sessions: скрипты-обёртки, хуки жизненного цикла, runners по требованию, MCP серверы и разрешения
  • Test end to end: CI smoke тест, который отправляет сеанс и читает ответы Claude