--- title: Начало работы с самостоятельно размещаемым Claude Managed Agents url: https://platform.claude.com/docs/ru/managed-agents/self-hosted/quickstart description: Запуск самостоятельно размещаемого Claude Managed Agents на одной машине с помощью Docker Compose и выполнение первого сеанса в контейнере песочницы. --- Чтобы запросить доступ к самостоятельно размещаемому Claude Managed Agents, обратитесь к команде, работающей с вашей учётной записью в Anthropic. В этом кратком руководстве вы запускаете самостоятельно размещаемый Claude Managed Agents на одной машине с помощью Docker Compose. Стек Compose состоит из сервера, его базы данных PostgreSQL и набора «workers» (воркеров), которые запускают каждый сеанс в отдельном «sandbox container» (контейнере песочницы), принадлежащем только этому сеансу. Затем вы общаетесь с агентом из терминала и убеждаетесь, что его вызовы инструментов выполнялись в контейнере песочницы. После этого вы можете открыть сеанс в [консоли на вашем сервере](https://platform.claude.com/docs/ru/managed-agents/self-hosted/console). Стек Compose предназначен для разработки, а не для промышленной эксплуатации. Он обслуживает обычный HTTP и по умолчанию публикует порт 8400 только на адресе обратной петли хоста Docker, `127.0.0.1`. В некоторых выпусках Docker Engine до 28.3.3 к этому порту также могут обращаться машины в локальной сети хоста. Инструменты агента выполняются в контейнерах на этом хосте, поэтому используйте машину, на которой нет ничего, что требуется защищать. Для промышленной эксплуатации Anthropic рекомендует два Helm-чарта из выпуска. См. [Развёртывание в Kubernetes](https://platform.claude.com/docs/ru/managed-agents/self-hosted/kubernetes). Позвольте Claude Code выполнить это краткое руководство за вас ```text Настрой самостоятельно размещаемый Claude Managed Agents на этой машине, следуя https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md. Я уже загрузил архив выпуска. ``` Если вы агент, который выполняет эти шаги для человека: * **Архив выпуска:** спросите человека, где находится архив. Загрузить его может только он. * **Ключ Claude API:** попросите человека самостоятельно отредактировать `.env`. Не запрашивайте ключ и не выводите содержимое `.env`. * **Переменные:** если ваша оболочка не сохраняет переменные между командами, задавайте `ANTHROPIC_BASE_URL` и `ANTHROPIC_API_KEY` заново в каждой команде `ant`. Без них `ant` обращается к размещённому сервису. * **Compose:** добавляйте `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` перед каждой командой `docker compose`, чтобы значения из вашей оболочки не попадали на сервер. * **Чат:** для `ant beta:sessions connect` нужен интерактивный терминал. Без него отправьте сообщение с помощью `ant beta:sessions:events send`, а ответ прочитайте с помощью `ant beta:sessions:events list`. Примеры приведены в разделах [Отправка событий](https://platform.claude.com/docs/ru/managed-agents/events-and-streaming#send-events) и [Список прошлых событий](https://platform.claude.com/docs/ru/managed-agents/events-and-streaming#list-past-events). * **Консоль:** выполняйте раздел «Опробуйте консоль на вашем сервере», только если человек об этом попросит. Если ваша оболочка не сохраняет переменные между командами, начиная с этого раздела также добавляйте `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` перед каждой командой `docker compose`. ## Предварительные требования * **Архив выпуска:** Чтобы запросить доступ к загрузке, обратитесь к команде по работе с вашим аккаунтом в Anthropic. * **Ключ Claude API:** сервер использует его для вызовов модели. Создайте его в [Claude Console](https://platform.claude.com/settings/keys). * **Docker:** [последняя версия Docker Engine](https://docs.docker.com/engine/install/) с плагином Compose (`docker compose`, а не старый `docker-compose`). * **Хост как минимум с двумя CPU:** x86-64 или Arm. На хосте меньшего размера при создании `.env` задайте для `CMA_SANDBOX_CPUS` число его CPU. * **Сетевой доступ при первом запуске:** первая сборка загружает данные из Docker Hub, репозиториев пакетов Alpine и релизов GitHub. * **Инструменты:** на машине, где вы запускаете Docker, нужны `openssl` и [CLI `ant`](https://platform.claude.com/docs/ru/cli-sdks-libraries/cli/quickstart#installation). ## Запуск стека Распакуйте архив и работайте из его каталога `compose`. В команде замените `` именем вашего архива без `.tar.gz`. ```bash tar -xzf .tar.gz && cd /compose ``` Если ваш umask строже `022`, исполняемые файлы теряют право на выполнение для других пользователей, и контейнер сервера не сможет их запустить. В этом случае установите umask `022` и распакуйте архив снова. Compose считывает секреты стека из файла `.env`, расположенного рядом с `docker-compose.yml`. Создайте файл: ```bash cat > .env < Соберите и запустите стек, а затем следите за журналом сервера: ```bash docker compose up --build -d docker compose logs -f cma-server ``` Когда в журнале появится строка с `msg="cma-server listening"`, нажмите Ctrl+C, чтобы прекратить его просмотр. ```bash curl -s http://127.0.0.1:8400/cma-server/readyz ``` Готовый сервер отвечает `"status":"ready"`. Сразу после запуска он может в течение нескольких секунд отвечать `"status":"degraded"`, пока выполняются его первые проверки. Если статус остаётся `degraded` или сервер отвечает `"status":"not_ready"`, см. [Устранение неполадок](https://platform.claude.com/docs/ru/managed-agents/self-hosted/quickstart#troubleshooting). ## Запуск первого сеанса Создайте агента и общайтесь с ним из терминала с помощью CLI `ant`. Откройте второй терминал в том же каталоге и используйте его для `ant`. Следующие команды задают для `ANTHROPIC_API_KEY` ключ API вашего сервера, а не ваш ключ Claude API, как описано в разделе [Вызов API на самостоятельно размещаемом сервере](https://platform.claude.com/docs/ru/managed-agents/self-hosted/call-the-api): ```bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8400 export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2) ``` Выполняйте команды `docker compose` в первом терминале. Если вы выполните `docker compose up` в этом терминале, Compose передаст эти переменные серверу, и сервер будет вызывать сам себя вместо Claude API. Сохраните файл, приведённый после команды, как `quickstart-agent.md`, а затем выполните команду. Этот файл даёт агенту встроенные инструменты и позволяет ему запускать их, не спрашивая вас заранее. ```bash CLI ant apply --yes quickstart-agent.md ``` ```markdown --- name: Quickstart agent model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful assistant. ``` Сначала команда выводит предупреждение о том, что ей `could not determine the organization and workspace`, с ошибкой `404`, а затем создаёт агента. На вашем собственном сервере это ожидаемо. Эти команды находят агента и окружение стека, запускают сеанс и сохраняют идентификатор сеанса в `SESSION_ID`. Стек присваивает своему окружению имя `compose-sandbox`. ```bash AGENT_ID=$(ant beta:agents list --format raw \ --transform 'data.#(name=="Quickstart agent").id' --raw-output) ENVIRONMENT_ID=$(ant beta:environments list --format raw \ --transform 'data.#(name=="compose-sandbox").id' --raw-output) SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" --transform id --raw-output) ``` Подключите терминал к сеансу: ```bash ant beta:sessions connect "$SESSION_ID" ``` Команда открывает [представление чата](https://platform.claude.com/docs/ru/cli-sdks-libraries/cli/sessions-connect) для сеанса. Отправьте это сообщение: ```text wrap Run `hostname` with the bash tool and tell me the output. ``` Агент отвечает именем хоста, начинающимся с `cma-sandbox-`. Это имя контейнера песочницы, в котором была выполнена команда, что подтверждает: инструмент работал в песочнице, а не на вашей машине. Не закрывайте чат. В первом терминале выведите список контейнеров песочницы: ```bash docker ps --filter label=cma-server.sandbox ``` В списке отображается контейнер, о котором сообщил агент. Контейнер завершает работу примерно через минуту после завершения хода, а следующее сообщение сеанса запускает новый контейнер. Если список пуст, снова попросите агента выполнить `hostname` и снова выведите список контейнеров, пока он отвечает. Чтобы выйти из чата, нажмите Ctrl+C в его терминале. Сеанс продолжит работать. ## Опробуйте консоль на вашем сервере Этот раздел необязателен. Для консоли требуется единый вход. Чтобы опробовать её, перезапустите стек с фиктивным поставщиком входа из выпуска. Порт 8080 на вашей машине должен быть свободен. Используйте фиктивный поставщик только с одноразовыми данными. Он выдаёт токен администратора любому, кто к нему обратится. В Docker Desktop к ним относятся и контейнеры песочницы. В некоторых выпусках Docker Engine до 28.3.3 — и машины в вашей сети. Выполните эти команды в первом терминале: ```bash export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml docker compose up --build -d ``` Строка `export` действует только в первом терминале, поэтому выполняйте её заново в любом новом терминале, который вы открываете для `docker compose`. Чтобы изменить настройки сервера в этом стеке, отредактируйте `compose.config.oidc.yaml`, а не `compose.config.yaml`, а затем выполните `docker compose restart cma-server`. В браузере на той же машине откройте `http://127.0.0.1:8400/`, нажмите **Continue with SSO** и выберите **alice** — демонстрационного администратора. На боковой панели выберите **Sessions**, а затем выберите сеанс. Страница обновляется по мере работы агента, и с неё можно отправить агенту сообщение. Чтобы также создавать агентов и запускать сеансы в консоли, см. [Запуск агента из консоли](https://platform.claude.com/docs/ru/managed-agents/self-hosted/console#run-an-agent-from-the-console). ## Остановка стека В первом терминале выполните эту команду: ```bash docker compose down --remove-orphans ``` Команда удаляет контейнеры и сохраняет базу данных. Чтобы удалить также базу данных со всеми агентами, сеансами и историей сеансов в ней, выполните `docker compose down --remove-orphans -v`. ## Устранение неполадок * **В вашем архиве нет каталога `compose`:** архив содержит более ранний выпуск, и команды на этой странице ему не соответствуют. Чтобы получить текущий выпуск, обратитесь к команде по работе с вашим аккаунтом в Anthropic. Чтобы перевести работающее развёртывание на текущий выпуск, см. [Обновление самостоятельно размещаемого Claude Managed Agents](https://platform.claude.com/docs/ru/managed-agents/self-hosted/upgrade). * **Сервер так и не запускается:** выполните `docker compose logs migrate`. Одноразовый контейнер `migrate` создаёт таблицы базы данных. Он должен завершиться со статусом `0` до запуска сервера. * **Проверка готовности остаётся в статусе `degraded` или каждый ход завершается ошибкой:** если вы выполнили `docker compose up` в терминале, где `ANTHROPIC_BASE_URL` имеет значение `http://127.0.0.1:8400`, сервер вызывает сам себя вместо Claude API. Снова выполните `docker compose up -d` в первом терминале, где эта переменная не задана. В противном случае причина сбоя указана в журнале сервера. Чтобы прочитать его, снова выполните `docker compose logs -f cma-server`. * **Проверка готовности отвечает `not_ready`:** найдите в ответе проверку с состоянием `failed`: * **`upstream`:** Claude API отклонил ваш ключ Claude API. Исправьте `ANTHROPIC_API_KEY` в `.env`, а затем в первом терминале снова выполните `docker compose up -d`. Если ваша оболочка тоже задаёт `ANTHROPIC_API_KEY`, Compose использует значение из оболочки, поэтому сначала выполните `unset ANTHROPIC_API_KEY`. * **`database`:** либо база данных отклонила вход сервера, например из-за неверного пароля, либо оборвалось открытое соединение с базой данных. Чтобы выяснить, что именно произошло, снова выполните `docker compose logs -f cma-server`. * **Агент отвечает, но его вызов инструмента так и не завершается:** ни один воркер не опрашивает окружение. Проверьте журнал воркеров с помощью `docker compose logs sandbox`. Воркер, который не может подключиться к сокету демона Docker, завершает работу с сообщением, в котором упоминается `CMA_DOCKER_SOCKET`. Задайте в `.env` для этой переменной путь к сокету вашего демона, а затем в первом терминале снова выполните `docker compose up -d`. * **Воркеры работают, но вызов инструмента всё равно так и не завершается:** стек запускает 10 воркеров, и каждый из них одновременно выполняет контейнер только одного сеанса. Сеанс занимает свободный воркер при создании, а сеанс, который так и не получает сообщения, удерживает свой воркер до часа. Когда заняты все 10, вызовы инструментов любого другого сеанса ждут воркера. Если команда `docker ps` на шаге «Найдите контейнер песочницы» выводит 10 контейнеров, архивируйте сеансы, которые вы не используете: 1. В первом терминале выполните `docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'`. Она выводит идентификатор сеанса, которому принадлежит каждый контейнер. У ожидающего сеанса ещё нет контейнера, поэтому его нет в списке. 2. Во втором терминале нажмите Ctrl+C, чтобы выйти из чата, и выполните `ant beta:sessions archive --session-id ` для каждого сеанса из списка, который вы не используете. 3. Снова выполните `ant beta:sessions connect "$SESSION_ID"`. Вызов инструмента завершится, когда воркер возьмёт его сеанс. ## Следующие шаги Направьте SDK и CLI `ant` на ваш сервер. Узнайте, какие функции работают иначе или недоступны. Настройте вход, создавайте агентов и запускайте сеансы в браузере.