SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Как развернуть OneCLI на своем сервере через Docker

Узнайте, как самостоятельно развернуть OneCLI с использованием Docker Compose и PostgreSQL. В статье приведены системные требования, включая лимит в 2 GiB RAM на агента.

Что вы получаете при самостоятельном развертывании OneCLI

Разверните OneCLI самостоятельно, и каждый участник вашей команды получит собственного агента, работающего в изолированной песочнице. API-ключи при этом хранятся на шлюзе, к которому агенты не имеют прямого доступа. Установка представляет собой стек Docker Compose с базой данных PostgreSQL, доступной по адресу http://localhost:10254. Планируйте использование выделенного сервера. Документированный лимит по умолчанию составляет 2 GiB оперативной памяти на песочницу агента, поэтому рассчитывайте ресурсы отдельно для базового стека и для фактической рабочей нагрузки агентов.

Стек состоит из восьми компонентов. Понимание их назначения упростит чтение этого руководства.

  • Веб-панель управления (Next.js), порт 10254. Создание агентов, чат, редактирование памяти и навыков, управление подключениями и секретами.
  • API-сервер, порт 10256. Управляющая часть: база данных, обработка диалогов, очереди задач.
  • Rust-шлюз, порт 10255. Перехватывает исходящие запросы от агентов и внедряет в них учетные данные.
  • Runner. В README этот компонент описан как «запускающий, приостанавливающий и завершающий работу песочниц агентов. Работает только на исходящий трафик и никогда не обращается к базе данных».
  • Sandbox Supervisor. В README указано, что он работает «внутри каждой песочницы, используя независимый от вендора интерфейс, что позволяет заменять среду выполнения агента».
  • SSH-терминатор, порт 10257. В README назван «SSH-входом»: он терминирует SSH-соединения с помощью краткосрочных сертификатов, выдаваемых API, и перенаправляет каждую сессию в песочницу агента. Работает под тем же профилем runner, что и runner.
  • Адаптер каналов. Демон, который подключает приложение Slack, позволяя агенту отвечать в каналах и личных сообщениях от своего имени.
  • PostgreSQL. Поставляемый файл compose запускает postgres:18-alpine с томом pgdata.

Название указывает на CLI, но продукт является сервером

OneCLI — это серверная платформа. Название отсылает к инструменту командной строки, который устанавливается на ноутбук, но это представление неверно для продукта из данного руководства. Отдельный клиент командной строки действительно существует в репозитории onecli/onecli-cli, он направляет трафик локального агента разработки через шлюз. То, что вы разворачиваете здесь, — это многопользовательское веб-приложение: система учетных записей с организациями и приглашениями, база данных диалогов и секретов, а также исполнитель (runner), который запускает контейнеры.

Модель «один агент на человека» лежит в основе архитектуры. Из README: «Вы создаете агента для каждого пользователя, предоставляете ему необходимый доступ, и он работает в изолированной среде (sandbox), направляемой через шлюз, который внедряет учетные данные и обеспечивает соблюдение ваших политик». У каждого агента есть собственная файловая система и оболочка, собственная страница диалога, память, которую хранит платформа, и навыки, которые вы пишете один раз. Учетные данные работают иначе, чем в стандартных настройках. Вместо копирования API-ключа в окружение каждого пользователя, вы сохраняете ключ один раз и предоставляете доступ к нему тем агентам, которым разрешено его использовать.

Что необходимо подготовить перед началом

  • Docker с плагином Compose версии 2.24.0 или новее. Используемый файл compose содержит опциональные маппинги env_file с required: false, которые поддерживаются в Docker начиная с версии 2.24.0. Комментарии к миграции указывают версию 2.19 как минимально допустимую для поддержки однократных зависимостей в up --wait, однако это не распространяется на опциональные файлы окружения, используемые в данном файле.
  • Оперативная память — это основной ограничивающий фактор. Ознакомьтесь с разделом по выбору размера ресурсов ниже, прежде чем выбирать тарифный план.
  • Свободные порты loopback 10254, 10255, 10256, 10257 и 5432. Порт 10257 используется для SSH-доступа, который запускается с профилем runner, активируемым в данном руководстве.

Вам не нужно устанавливать PostgreSQL самостоятельно: файл compose запускает его как сервис. Мастер настройки, описанный ниже, требует наличия Node.js и pnpm на хосте. Работа с исходным кодом также использует mise для фиксации версий инструментов, включая Rust для шлюза.

Сколько песочниц агентов поместится на вашем VPS?

Документация раннера содержит конкретные цифры, а не приблизительные оценки. Каждая песочница ограничена 2048 МБ оперативной памяти (RUNNER_SANDBOX_MEMORY_MB), одним процессором (RUNNER_SANDBOX_CPUS) и 512 процессами (RUNNER_SANDBOX_PIDS). Лимит параллельного выполнения составляет 4 (RUNNER_MAX_SANDBOXES), при этом документация рекомендует иметь около 10 ГБ свободной оперативной памяти сверх базового стека для обеспечения этого лимита.

ГрафикAgent memory budgets per box, using the documented 2 GiB cap
Данные, на которых построен график
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Количество слотов рассчитывается арифметически, а не на основе бенчмарков: общий объем памяти минус примерно 2 ГБ, зарезервированные для PostgreSQL и других постоянно работающих сервисов, деленный на лимит песочницы в 2 ГБ. Исходя из этого, 2 GB box определяет бюджет для 0 песочниц при их полном использовании памяти; значение ноль означает отсутствие бюджета для полной нагрузки при данных допущениях, а не отказ Docker запускать агент. План 16 GB box оставляет место для 7 песочниц, что комфортно превышает стандартный лимит в четыре и соответствует требованию документации о 10 ГБ свободной памяти. План 32 GB box дает 15. Запуск более четырех песочниц одновременно также требует увеличения RUNNER_MAX_SANDBOXES.

Два фактора меняют этот расчет. Песочница с работающим фоновым процессом никогда не переходит в режим ожидания и постоянно занимает свой слот, поэтому RUNNER_MAX_SANDBOXES следует рассчитывать исходя из устойчивой нагрузки, а не пиковых значений. Платформа ограничивает это поведение: по умолчанию каждый раннер удерживает не более RUNNER_MAX_SANDBOXES минус один активных песочниц (но не менее одной, значение можно изменить через MAX_HELD_AWAKE_SANDBOXES в API). При превышении этого числа раннер удаляет песочницу, которая дольше всех простаивала, и сообщает о потере отслеживаемого процесса. Потребление памяти и процессора зависит от выполняемой задачи. Каждая песочница ограничена одним ядром процессора, поэтому четыре активных агента могут использовать четыре ядра, но лимит в 2 ГБ памяти — это потолок, а не резервирование: четыре простаивающих, но запущенных агента не потребляют автоматически 8 ГБ.

Настройки раннера, которые вы можете изменить
  • RUNNER_MAX_SANDBOXES (по умолчанию 4): сколько песочниц запускается одновременно.
  • RUNNER_SANDBOX_MEMORY_MB (по умолчанию 2048): лимит памяти на одну песочницу.
  • RUNNER_SANDBOX_CPUS (по умолчанию 1): лимит процессора на одну песочницу.
  • RUNNER_SANDBOX_PIDS (по умолчанию 512): лимит процессов на одну песочницу.
  • RUNNER_NETWORK_INTERNAL (по умолчанию true): ограничивает сеть песочницы без доступа наружу. Оставьте включенным.
  • RUNNER_SANDBOX_NETWORK (по умолчанию onecli-sandboxes): сеть, к которой подключаются песочницы.
  • RUNNER_RECONCILE_SECONDS (по умолчанию 60): как часто раннер синхронизирует состояние.
  • RUNNER_ORPHAN_GRACE_SECONDS (по умолчанию 3600): возраст, по достижении которого удаляются осиротевшие контейнеры и тома.
  • RUNNER_AGENT_IMAGE: переопределяет образ песочницы, который в противном случае определяется через ONECLI_VERSION.

Установка OneCLI с помощью Docker Compose

В исходной документации по self-hosting предлагается записать три секрета в файл docker/.env рядом с файлом compose. Эта последовательность не учитывает токен runner, группу Docker socket и SSH-учетные данные, необходимые для запускаемых сервисов, поэтому перед запуском стека выполните мастер настройки.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Прочитайте этот блок перед выполнением. Маркер heredoc не взят в кавычки, поэтому оболочка выполнит каждую команду head -c 32 /dev/urandom | base64 и запишет результат, а не сам текст. SECRET_ENCRYPTION_KEY — это ключ AES-256-GCM для всех секретов в базе данных. GATEWAY_INTERNAL_SECRET аутентифицирует шлюз в API. BETTER_AUTH_SECRET подписывает файлы cookie сеанса. COMPOSE_PROFILES=runner — самая важная строка, так как сервис runner находится за профилем Compose: если её пропустить, стек запустится без ошибок, но песочница агента (agent sandbox) не будет запущена.

--wait ожидает, пока сервисы запустятся или перейдут в состояние healthy, а зависимость миграций успешно завершится, поэтому ненулевой код выхода — первый признак того, что что-то пошло не так. После этого проверьте, какие именно контейнеры были запущены.

docker compose ps
docker compose logs migrations

Зафиксируйте версию. ONECLI_VERSION устанавливает тег для всех сервисов сразу, и образ песочницы агента будет использовать его, если RUNNER_AGENT_IMAGE не указывает на другое место. Используйте только номер версии: опубликованные теги образов не содержат префикс v. По состоянию на 1 ноября 2026 года текущий релиз — v2.17.0, опубликованный 31 октября 2026 года. Добавьте его в тот же файл, а затем используйте документированный путь обновления, чтобы запущенные песочницы также перешли на этот образ.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

Также существует установщик curl -fsSL https://onecli.sh/install | sh, который записывает конфигурацию в ~/.onecli/.env и выполняет ту же работу. Он устанавливает ONECLI_VERSION=latest для своего запуска, что переопределяет фиксацию версии, хранящуюся только в файле .env. Путь с использованием Compose позволяет прочитать каждый файл перед запуском чего-либо, и именно его следует использовать на сервере, где уже работают другие стеки Compose. Описанный выше процесс через checkout обновляется с помощью pnpm run setup --upgrade. Этот путь требует наличия Node.js и pnpm на хосте, а работа с самим кодом добавляет mise и Rust для шлюза, поэтому он подходит тем, кто планирует вносить изменения в OneCLI. Для Kubernetes в релизе v2.11.0 (8 октября 2026 года) был добавлен Helm chart; текущий чарт запускает песочницы агентов как Jobs с постоянными томами (persistent volumes), без Docker daemon, а также содержит документацию по необходимым секретам, базе данных и конфигурации маршрутизации.

Доступ к панели управления с вашего ноутбука

Все опубликованные порты в поставляемом файле compose привязаны к ${ONECLI_BIND_HOST:-127.0.0.1}. На VPS это означает, что панель управления запущена, но извне сервера доступ к ней закрыт. Это стандартное и правильное поведение. Оставьте его и используйте туннель:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Теперь откройте http://localhost:10254 на вашем ноутбуке. Трафик передается через SSH-соединение, поэтому панель управления не передается в открытом виде через публичный интернет, и нет необходимости открывать дополнительные порты в межсетевом экране.

Настройка ONECLI_BIND_HOST=0.0.0.0 публикует панель управления по обычному HTTP, а также публикует PostgreSQL вместе с ней, используя пароль по умолчанию из файла compose — onecli, если вы не задали POSTGRES_PASSWORD. Это также публикует SSH-шлюз на порту 10257 — сервис, который монтирует Docker socket. Если панель управления нужна нескольким пользователям, установите перед ней reverse proxy с TLS (transport layer security), не меняя привязку к хосту. Установите ONECLI_EXTERNAL_URL в значение HTTPS URL и используйте конфигурацию reverse proxy от разработчика, которая направляет запросы к панели управления, API и шлюзу на соответствующие сервисы. Сам по себе прокси не защищает от посторонних. В документации по self-hosting указано, что регистрация открыта по умолчанию и её невозможно отключить: любой, кто получил доступ к панели управления, может создать учетную запись, которая получит собственную организацию, а приглашение требуется только для вступления в вашу организацию. Рекомендуется держать панель управления внутри границ вашей сети. Если этот прокси уже обслуживает другие ваши self-hosted приложения, настройте forward auth через self-hosted систему единого входа (SSO), чтобы скрыть панель управления за уже существующим механизмом авторизации вашей команды. Таким образом, удаление пользователя в одном месте закроет ему доступ и здесь.

Создание первой учетной записи и предоставление ключа модели

Откройте панель управления и сразу создайте свою учетную запись. Каждая новая учетная запись получает собственную организацию, а коллеги присоединяются к вашей по приглашению. Регистрация остается открытой и после этого, что является еще одной причиной разместить панель управления за туннелем или прокси-сервером с аутентификацией. Если вы обновляетесь с версии, выпущенной до появления системы входа, зарегистрируйтесь немедленно: в документации по self-hosting указано, что существующие данные привязываются к первой зарегистрированной учетной записи, поэтому на доступном извне хосте эта учетная запись должна принадлежать вам.

Затем сохраните ключ модели, прежде чем создавать агента. Размещенному агенту требуется предоставленный ключ модели, и порядок действий имеет значение: сохраните ключ в панели управления, предоставьте его агенту и только после этого начинайте диалог. Если пропустить этап предоставления доступа, песочница не запустится; агент ответит в ветке обсуждения, что ему необходим ключ модели.

Предоставляйте доступ избирательно. Каждый агент получает только то, что вы ему разрешили, и шлюз принудительно применяет это ограничение для каждого запроса, поэтому агент, имеющий доступ к одному репозиторию, не сможет получить ключ от вашего платежного провайдера. Тот же список разрешений является вашим инструментом контроля расходов. Агент, закрепленный за пользователем и имеющий доступ к любой вашей модели, означает персональный счет, поэтому стоит ознакомиться с тем, как ограничить расходы агента на вызовы моделей, прежде чем раздавать их десятками.

Как шлюз защищает ключи от агентов

Шлюз — это HTTPS-прокси, написанный на Rust, который ожидает соединений на порту 10255. HTTP-клиент агента настроен на работу через этот прокси, при этом агент использует фиктивные учетные данные вместо реальных. Шлюз сопоставляет исходящий запрос с правами доступа конкретного агента, расшифровывает настоящий секрет, подставляет его в запрос и пересылает дальше. Секреты хранятся в PostgreSQL в зашифрованном виде с использованием AES-256-GCM (Advanced Encryption Standard, 256 бит, режим Galois/Counter) и расшифровываются только в момент запроса. Каждый вызов протоколируется с указанием идентификатора агента и цели запроса, что создает контрольный журнал, который невозможно получить, если ключи хранятся в профилях оболочки у десяти разных пользователей.

Развертывание определяется двумя механизмами.

  • Перехват HTTPS работает по принципу man-in-the-middle. Шлюз генерирует локальный центр сертификации, агент доверяет ему, а шлюз терминирует TLS-соединение агента и открывает новое соединение с целевым сервисом. Именно поэтому агент, чей HTTP-клиент не доверяет центру сертификации шлюза, выдает ошибку проверки сертификата, а не ошибку аутентификации.
  • Агент идентифицирует себя с помощью заголовка Proxy-Authorization. На одном узле, где агенты и шлюз находятся в общей внутренней сети Docker, этот заголовок не покидает контролируемую вами сеть. Если вы подключаете внешний агент к шлюзу, защитите соединение с помощью VPN или TLS-транспорта, так как этот заголовок является bearer-токеном; разработчики рекомендуют использовать VPN для прямого порта CONNECT-прокси.

Честный компромисс: шлюз по своей архитектуре читает каждый запрос ваших агентов в открытом виде. Это самый критически важный процесс на машине. Относитесь к хосту, на котором он запущен, соответствующим образом и ограничьте количество пользователей, имеющих доступ к системе, следуя принципу минимальных привилегий для пользователей Linux.

Почему раннеру не нужны входящие порты

Раннер работает только на исходящие соединения. В документации сказано: «он не открывает портов, доступных извне, поэтому ноутбук, домашняя лаборатория или VPC за NAT работают без входящих соединений, туннелей и настройки TLS termination». NAT — это трансляция сетевых адресов, которую выполняет домашний роутер. Раннер сам устанавливает соединение с control plane и забирает оттуда задачи, поэтому ничего не нужно пробрасывать или открывать.

Такая архитектура полезна для сети песочницы (sandbox). Файл compose определяет вторую сеть, помеченную internal: true, что в Docker означает отсутствие внешнего сетевого подключения. Песочницы подключаются к ней. Шлюз имеет интерфейсы в обеих сетях, поэтому он является единственным выходом наружу. В документации раннера этот момент описан прямо: «сеть internal, в которой шлюз имеет два интерфейса, превращает ограничение исходящего трафика через шлюз в реальную границу, а не просто рекомендацию». Агент не может обойти шлюз, открыв прямое соединение с внешним адресом; политика шлюза по-прежнему определяет, какие запросы разрешены.

Проверьте это на своем сервере, вместо того чтобы доверять тексту выше.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Вы должны увидеть "Internal": true. Если выводится false, контроль исходящего трафика отключен, и шлюз снова является лишь рекомендацией. Используйте то имя сети песочницы, которое выводит docker network ls, так как onecli-sandboxes — это только значение по умолчанию.

Насколько надежна песочница OneCLI?

Читайте этот раздел внимательно, так как термин «песочница» (sandboxed) в описании проекта имеет большой вес, в то время как сам механизм описан в документации к runner и коде бэкенда.

В README указано, что каждый агент получает «свою изолированную песочницу с файловой системой и оболочкой», а также упоминается Sandbox Supervisor как компонент, который «работает внутри каждой песочницы, используя независимый от вендора интерфейс, что позволяет заменять среду выполнения агента». Ни одно из этих предложений не уточняет, из чего именно состоит изоляция. Документация runner дает ответ: бэкендом по умолчанию является Docker (RUNNER_BACKEND=docker), а песочница представляет собой Docker-контейнер с ограничениями по памяти, процессору и количеству процессов, подключенный к внутренней сети. В коде предусмотрены возможности для использования других бэкендов. Текущий код runner также реализует бэкенд для Kubernetes, который Helm-чарт использует для Jobs и постоянных томов (persistent volumes) в песочницах. В установке через Compose, описанной в этом руководстве, песочница является Docker-контейнером.

Документация runner теперь описывает границы Docker: агент работает как node, с no-new-privileges, всеми сброшенными Linux capabilities и стандартным профилем seccomp в Docker. Бэкенд монтирует в песочницу только постоянную домашнюю директорию агента. Поэтому воспринимайте описание буквально. Указанные ограничения — это ограничения ресурсов. Внутренняя сеть обеспечивает реальный контроль исходящего трафика. Изоляция между агентом и хостом использует стандартные средства контейнеризации, а контейнер совместно использует ядро хоста.

Существует второй факт, который необходимо учитывать. Сервис runner монтирует /var/run/docker.sock, так как именно так он создает песочницы. Доступ к сокету Docker-демона с правами root эквивалентен получению прав root на хосте, поскольку любой, кто может обращаться к этому API, способен запустить контейнер с примонтированной файловой системой хоста. Поставляемый runner на базе Docker использует этот сокет. Следствием этого является то, что процесс runner столь же критичен, как и шлюз. SSH-терминатор монтирует тот же сокет, чтобы иметь возможность выполнять команды внутри контейнеров песочниц, и в комментариях к compose-файлу это монтирование прямо называется эквивалентным доступу root на хосте. Поэтому держите порт 10257 на loopback, если у вас нет веских причин открывать его.

Относитесь к границе с общим ядром консервативно. На практике это означает три правила:

  1. Запускайте OneCLI на отдельной машине, которая не выполняет других задач. Никаких сторонних рабочих сервисов, общих баз данных или данных других команд.
  2. Исходите из того, что агент, получивший возможность произвольного выполнения кода внутри своей песочницы, может добраться до хоста. Сделайте такой сценарий допустимым, храня резервные копии вне этого сервера.
  3. Прочитайте apps/runner/src или уточните у разработчиков, прежде чем утверждать коллегам, что агент полностью изолирован.

Чтобы понять, как выглядит документированная граница безопасности и какие вопросы стоит задавать разработчикам, сравните это с тем, как выглядит реальная граница песочницы агента. Вопрос заключается в том, покрывает ли документированный механизм те угрозы, от которых вам необходимо защититься.

Разделение лицензий: почему стоит проверить условия перед сборкой

Ядро OneCLI распространяется по лицензии Apache-2.0, что позволяет использовать его для self-hosting в production. Директории с именем ee/ подпадают под действие отдельной лицензии OneCLI Enterprise License: она бесплатна для разработки, тестирования и оценки, однако для использования в production требуется подписка. В примечаниях к релизу v2.0.1 от 18 августа 2026 года упоминается восстановление файла лицензии Apache-2.0, который распознается GitHub, поэтому значок на странице репозитория недавно изменился. Проверяйте тег, который вы фактически развертываете, а не сводную информацию, написанную в другую дату.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Все, что находится по этим путям, относится к коммерческой части. Если функция, на которую вы планируете опираться, находится там, оцените стоимость перед тем, как выстраивать вокруг нее рабочий процесс.

Обновления, миграции и один файл, который нельзя потерять

Обновления должны обновлять образы сервисов и отдельный образ агента, а затем перезапускать работающие песочницы. Сервис миграции, работающий в режиме one-shot, запускается перед API при каждом up. Если миграция завершается неудачей, стек отказывается запускаться, вместо того чтобы работать с частично обновленной схемой. Это именно то поведение, которое вам нужно: неудачное обновление выглядит как простой сервиса, а не как скрытое повреждение данных, и docker compose logs migrations объясняет почему.

Один шаг легко пропустить. Документация по self-hosting предостерегает от обновления с помощью простого docker compose pull && docker compose up -d, так как образ песочницы агента не является сервисом Compose. Это значение RUNNER_AGENT_IMAGE в настройках раннера, поэтому docker compose pull его не отслеживает, и размещенные агенты могут оставаться на старом образе песочницы без каких-либо предупреждений. Обновите checkout, измените привязку версии и запустите задокументированную утилиту обновления, которая скачает образ песочницы и перезапустит работающие песочницы.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Замените 2.17.0 на версию, на которую вы переходите. Перезапуск песочниц прерывает текущие задачи; при этом постоянное рабочее пространство каждого агента сохраняется.

Если вы использовали установочный скрипт, повторно запустите его, вместо того чтобы выполнять обновление вручную. Это позволит поддерживать файл compose в актуальном состоянии относительно образов, на которые он ссылается. Сначала экспортируйте ONECLI_VERSION, если вам нужна конкретная версия, так как скрипт переопределяет привязку, хранящуюся только в его файле .env.

Создавайте резервные копии базы данных, конфигурации и томов рабочих пространств агентов. В PostgreSQL хранятся агенты, диалоги, память и зашифрованные секреты. Файл docker/.env содержит SECRET_ENCRYPTION_KEY, и без этого ключа зашифрованные секреты невозможно прочитать, даже если остальная часть базы данных будет восстановлена. /workspace каждого агента находится на отдельном постоянном томе и требует собственного резервного копирования.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Храните эти копии и резервные копии рабочих пространств вне сервера. Процедура такая же, как и для любого стека Compose с сохранением состояния. Если вы уже настроили резервное копирование и обновление стека Docker Compose по расписанию, добавьте в него базу данных, конфигурацию и тома рабочих пространств, и вопрос будет решен.

Если что-то не работает

  • Стек не переходит в состояние healthy, а docker compose up -d --wait завершается с ненулевым кодом выхода. Сначала изучите docker compose logs migrations, так как API намеренно ожидает этот сервис.
  • Агент простаивает, а sandbox не появляется. Убедитесь, что COMPOSE_PROFILES=runner находится в docker/.env, а в docker compose ps отображается runner. Затем проверьте, что агенту предоставлен ключ модели, так как без него sandbox не запускается.
  • Нет свободных слотов. RUNNER_MAX_SANDBOXES по умолчанию равен 4, и sandbox с запущенным фоновым процессом удерживает свой слот, пока его не вытеснит лимит времени удержания. docker ps показывает, что работает на самом деле.
  • Стек не запускается, и Docker сообщает, что порт уже используется. При включенном профиле runner SSH-шлюз требует порт 10257 в дополнение к остальным четырем портам.
  • Контейнеры исчезают или хост начинает тормозить. Проверьте, не исчерпана ли память с помощью dmesg -T | grep -i oom; лимит памяти по умолчанию позволяет одному sandbox использовать до 2048 MB.
  • HTTPS-запросы агента завершаются ошибками проверки сертификата, а не ошибками аутентификации. Его HTTP-клиент не доверяет центру сертификации шлюза.
  • Старые контейнеры или тома остаются после удаления агента. Runner выполняет сверку каждые 60 секунд и удаляет «сироты» старше RUNNER_ORPHAN_GRACE_SECONDS (значение по умолчанию — 3600), поэтому подождите час, прежде чем считать это утечкой.

Подходит ли вам это решение?

Тест на соответствие требованиям занимает мало времени. OneCLI оправдывает себя, когда нескольким пользователям нужен агент, а вы хотите хранить учетные данные в одном месте: единое хранилище для ротации, один журнал аудита для чтения и одна панель управления, где отзыв доступа для пользователя действительно его отменяет. Это реальная эксплуатационная задача, и копирование API key на шесть ноутбуков — худшее решение.

Для одного пользователя это слишком сложная инфраструктура без практической пользы. Вам пришлось бы запустить PostgreSQL, control plane, gateway и runner, чтобы предоставить себе одного агента. При этом проблема с учётными данными, которую решает gateway, почти отсутствует, если единственный держатель ключа — вы. Вместо этого запустите один harness на менее мощном сервере: один harness агента на VPS выполняет эту задачу, используя лишь небольшую долю памяти. Если вы ещё не выбрали направление, сначала изучите обзор сравнение self-hosted AI-агентов — это более экономичный первый шаг. Если вам пока незнакомы именно агенты, а не серверы, на которых они работают, сначала пройдите поэтапный путь к пониманию принципов работы агентов. Понимание того, как на самом деле работают вызовы инструментов и хранилища памяти, поможет определить, какие разрешения должен получить агент каждого пользователя.

FAQ

Каковы минимальные требования к серверу для самостоятельного размещения OneCLI?

Docker с плагином Compose версии 2.24.0 или новее, Node.js и pnpm для мастера настройки, а также достаточный объем оперативной памяти. PostgreSQL входит в состав файла compose, поэтому устанавливать его отдельно не нужно. Объем памяти определяет выбор тарифа: раннер по умолчанию ограничивает каждую песочницу агента 2048 МБ, а документация рекомендует иметь около 10 GiB свободной памяти сверх базового стека для обслуживания стандартного лимита в четыре песочницы. При расчете базового стека в 2 ГБ, сервер с 4 ГБ памяти позволяет запустить одну песочницу на полном лимите, а сервер с 16 ГБ покрывает стандартный лимит параллельных задач. Это оценочные показатели, а не измеренные минимальные требования или фиксированные объемы выделяемой памяти.

Нужен ли OneCLI PostgreSQL или можно использовать SQLite?

Требуется PostgreSQL. DATABASE_URL задокументирован как строка подключения к PostgreSQL, поставляемый файл compose запускает postgres:18-alpine с томом pgdata, а отдельный сервис миграций применяет схему до запуска API. Опция использования SQLite не задокументирована. Для использования внешнего сервера PostgreSQL настройте API и сервис миграций на работу с ним; поставляемый файл compose устанавливает их строки подключения на встроенный сервис PostgreSQL.

Является ли песочница агента OneCLI реальным рубежом безопасности?

Задокументированный механизм Compose представляет собой Docker-контейнер с ограничениями по памяти, процессору и процессам, подключенный к сети с меткой internal: true, чтобы внешний трафик проходил через шлюз. Контроль исходящего трафика реален, его можно проверить с помощью docker network inspect. Агент работает от имени node, с no-new-privileges, с отключенными возможностями Linux (capabilities) и стандартным профилем seccomp Docker, при этом разделяя ядро хоста. Раннер и SSH-терминатор монтируют /var/run/docker.sock, что эквивалентно правам root на хосте при использовании Docker-демона с root-доступом. Запускайте OneCLI на выделенном сервере и храните резервные копии вне этого сервера.

Нужно ли открывать входящие порты для OneCLI?

Нет. Раннер работает только на исходящие соединения и не открывает порты, доступные извне, поэтому он работает за NAT без использования туннелей. Файл compose по умолчанию привязывает панель управления, шлюз, API, PostgreSQL и, в профиле runner, SSH-вход на порту 10257 к 127.0.0.1. Получайте доступ к панели управления через SSH-туннель или используйте конфигурацию reverse proxy с TLS и необходимыми маршрутами для панели, API и шлюза, если доступ нужен нескольким пользователям. Помните, что регистрация остается открытой для любого, кто имеет доступ к сервису. Шлюз на порту 10255 предназначен для агентов, и на одном сервере эти агенты обращаются к нему через внутреннюю сеть Docker.

Можно ли бесплатно использовать OneCLI внутри компании?

Ядро распространяется под лицензией Apache-2.0, и его использование в производственной среде при самостоятельном размещении разрешено без коммерческой лицензии. Директории с именем ee/ покрываются лицензией OneCLI Enterprise License, которая бесплатна для разработки, тестирования и оценки, но требует подписки для использования в продакшене. Разделение компонентов меняется от релиза к релизу, а примечания к версии v2.0.1 от 18 августа 2026 года упоминают восстановление файла лицензии Apache-2.0, распознаваемого GitHub. Проверяйте LICENSE и директории ee/ в конкретном теге, который вы развертываете, прежде чем строить рабочий процесс на какой-либо отдельной функции.

Была ли эта статья полезной?