# Пошаговое руководство: как запустить автономных ИИ-агентов в безопасном рантайме OpenShell

> AI Release · @ai_release1 · https://ai-release.org/guides/poshagovoe-rukovodstvo-kak-zapustit-avtonomnyh-ii-agent.html

## TL;DR
- Время выполнения: 60–90 минут (точная установка зависит от того, насколько полно она описана в README репозитория)
- Уровень сложности: Advanced
- Понадобится: Linux-хост (Ubuntu 22.04+ или аналог) с sudo, `git`, Docker + плагин Compose, от 8 ГБ ОЗУ и 20 ГБ диска под образы, API-ключ вашей модели, доступ в интернет для клонирования репозитория
- Проверено по источнику: репозиторий `github.com/NVIDIA/OpenShell`, описание — «safe, private runtime for fleets of autonomous AI agents». Детали реализации, лицензия и поддерживаемые платформы в анонсе не раскрыты — **сверьтесь с документацией** в самом репозитории.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-zapustit-avtonomnyh-ii-agent-ru-1.jpg)

- ОС: Linux (Ubuntu 22.04+). Рантайм рассчитан на флоты агентов, поэтому запускать его на рабочем ноутбуке не стоит — берите отдельную ВМ или выделенный хост. Как поднять такой хост и что на нём разместить, разобрано в гайде [Как подключить ИИ к домашнему серверу](https://ai-release.org/guides/kak-podklyuchit-ii-k-domashnemu-serveru-poshagovoe-ruko.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).
- Права: пользователь с `sudo` (нужен для установки Docker и правил файрвола).
- Пакеты: `git`, `docker`, `docker compose`, `curl`.
- API-ключ модели: держите его в отдельном файле или менеджере секретов, не в репозитории. Провайдер и формат ключа зависят от вашей модели — **сверьтесь с документацией**.
- Диск: минимум 20 ГБ свободно (`df -h /`), потому что каждый образ агента и его артефакты занимают место.
- Сеть: исходящий доступ на 443 к `github.com` и к эндпоинту модели.

**Пример:** проверка базы перед стартом.

```bash
docker --version
git --version
df -h / | tail -1
```
Ожидаемый вывод — три строки: версия Docker (`Docker version 24.x` или новее), версия git (`git version 2.x`), и строка с `Avail` не меньше `20G`.

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

## Шаг 1. Разверните изолированный хост и получите исходники OpenShell

**Что сделать:** подключитесь к выделенному хосту по SSH и склонируйте репозиторий NVIDIA.

```bash
ssh <пользователь>@<ip-хоста>
mkdir -p ~/work && cd ~/work
git clone https://github.com/NVIDIA/OpenShell.git
cd OpenShell
ls -la
```

**Зачем:** OpenShell — это рантайм, то есть программа, которая запускает и ограничивает другие процессы. Исходники дают вам манифесты запуска и документацию; без чтения README дальше идти нельзя, потому что детали реализации в анонсе не публиковались.

**Как проверить:** команда `ls -la` должна показать содержимое репозитория, а следующая — текст README.

```bash
cat README.md | head -60
```

**Пример:** если в README есть раздел установки, вы увидите строки вида `## Installation` или `## Quickstart`. Если README пустой или содержит только описание проекта — установка ещё не документирована, сверьтесь с Issues и остальными файлами:

```bash
grep -ril "docker\|compose\|requirements\|pyproject" . --include="*.md" --include="*.yaml" --include="*.yml" --include="*.toml" | head -20
```

По этой выборке видно, чем проект собирается: `Dockerfile`, `docker-compose.yml`, `pyproject.toml` или `requirements.txt`. Почему это работает: менеджеры зависимостей и контейнеризация всегда оставляют в репозитории один из этих файлов.

## Шаг 2. Настройте изоляцию рантайма и запустите первый агент
![Иллюстрация к разделу «Шаг 2. Настройте изоляцию рантайма и запустите первый агент»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-zapustit-avtonomnyh-ii-agent-ru-2.jpg)


**Что сделать:** соберите образ и опишите политику ограничений — сеть, права, файловая система, лимиты. Это ключевой этап: безопасность даёт не сам OpenShell, а конфигурация, с которой вы его запускаете.

**Зачем:** автономный агент — программа, которая сама решает, какие команды выполнять. Если дать ей сеть без ограничений и права root, «приватный рантайм» превратится в обычный контейнер с полным доступом наружу.

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

```bash
grep -n "docker run\|docker compose\|image:" README.md docker-compose.yml 2>/dev/null | head -20
```

**Пример:** типовая безопасная команда запуска. Имя образа и тег в анонсе не публиковались — подставьте значения из README (**сверьтесь с документацией**), здесь они обозначены как `<openshell-image>:<tag>`.

```bash
docker build -t <openshell-image>:<tag> .   # если в репозитории есть Dockerfile
docker run -d \
  --name openshell-agent-01 \
  --user 10001:10001 \
  --read-only \
  --tmpfs /tmp:rw,size=256m \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --memory 4g --cpus 2 \
  --env-file ./agent.env \
  -v /srv/openshell/artifacts:/work/artifacts \
  <openshell-image>:<tag>
```

Файл `agent.env` создайте рядом, права `600`:

```bash
printf 'MODEL_API_KEY=%s\nMODEL_ENDPOINT=%s\n' "<ваш-ключ>" "https://<эндпоинт-модели>/v1" > agent.env
chmod 600 agent.env
```

**Как проверить:** контейнер должен быть в статусе `Up`, а внутри — не root и только для чтения.

```bash
docker ps --filter name=openshell-agent-01
docker exec openshell-agent-01 id
```
Ожидаемый результат: в `docker ps` статус `Up ...`, а `id` возвращает `uid=10001 gid=10001`, не `uid=0(root)`.

Чек-лист перед тем, как пускать агента в работу:

- [ ] контейнер работает от non-root (`--user`)
- [ ] корневая ФС смонтирована read-only (`--read-only`)
- [ ] сброшены capabilities (`--cap-drop ALL`) и запрещён эскалационный запуск (`no-new-privileges`)
- [ ] заданы лимиты памяти и CPU
- [ ] секреты приходят через `--env-file`, а не зашиты в образ
- [ ] артефакты агента пишутся в отдельный volume, а не в слой образа
- [ ] исходящая сеть ограничена allowlist адресов модели и реестра пакетов

Последний пункт проверяется правилами файрвола или прокси:

```bash
sudo ufw default deny outgoing
sudo ufw allow out 53/udp
sudo ufw allow out 443/tcp to <ip-эндпоинта-модели>
sudo ufw enable
```
Почему это работает: агент обращается только к DNS и к конкретному адресу модели, любой другой исходящий запрос отбрасывается на уровне ядра, а не внутри приложения.

## Шаг 3. Проверьте изоляцию и убедитесь, что агент работает
![Иллюстрация к разделу «Шаг 3. Проверьте изоляцию и убедитесь, что агент работает»](https://ai-release.org/guides/img/poshagovoe-rukovodstvo-kak-zapustit-avtonomnyh-ii-agent-ru-3.jpg)


**Что сделать:** прогоните три проверки — доступность разрешённого эндпоинта, блокировка запрещённого и запись артефакта.

```bash
docker exec openshell-agent-01 sh -c 'curl -sS -m 5 -o /dev/null -w "%{http_code}\n" https://<эндпоинт-модели>/v1/models'
docker exec openshell-agent-01 sh -c 'curl -sS -m 5 https://example.org ; echo "exit=$?"'
```
**Как проверить:** первая команда печатает `200` (или `401` — если ключ не передан, это тоже признак, что сеть открыта), вторая — ошибку соединения и `exit=28` (таймаут) либо `exit=7` (нет соединения). Если вторая команда вернула HTML — изоляция не работает, вернитесь к правилам `ufw`.

**Пример:** если `curl` в образе нет, используйте Python, который обычно есть в образах под агентов:

```bash
docker exec openshell-agent-01 python3 -c "import urllib.request;print(urllib.request.urlopen('https://example.org',timeout=5).status)"
```
Ожидаемо: `urllib.error.URLError` или `TimeoutError`. Отсутствие ответа — это и есть успех проверки.

Финальная проверка записи артефакта:

```bash
docker exec openshell-agent-01 sh -c 'touch /work/artifacts/probe && echo ok' && ls -l /srv/openshell/artifacts/
```
На экране — `ok` и строка `probe` в листинге каталога. При этом запись в корень должна падать: `docker exec openshell-agent-01 touch /probe` вернёт `Read-only file system`.

Когда несколько агентов работают подолгу, имеет смысл вывести их статусы в Telegram — схема описана в гайде [Как настроить мониторинг VPS через Telegram-бота с Mini App](https://ai-release.org/guides/kak-nastroit-monitoring-vps-cherez-telegram-bota-s-mini.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Возможные проблемы и решения

**Проблема. Репозиторий не клонируется**
- Ошибка: `fatal: repository 'https://github.com/NVIDIA/OpenShell.git/' not found`
- Причина: репозиторий переименован, перенесён или доступ ограничен; проект молодой, путь мог измениться.
- Решение: откройте организацию и уточните актуальный адрес, затем повторите клонирование.
```bash
curl -s https://api.github.com/orgs/NVIDIA/repos?per_page=100 | grep -o '"clone_url": "[^"]*OpenShell[^"]*"'
git clone <полученный-URL>
```

**Проблема. Docker не запускается от текущего пользователя**
- Ошибка: `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`
- Причина: пользователь не входит в группу `docker`, у демона другой владелец сокета.
- Решение: добавьте пользователя в группу и перезайдите в сессию.
```bash
sudo usermod -aG docker $USER
newgrp docker
docker ps
```

**Проблема. Агент не может обратиться к модели**
- Ошибка: `curl: (28) Connection timed out after 5001 milliseconds` внутри контейнера
- Причина: правило `ufw` пропускает только разрешённые адреса, а реальный IP эндпоинта из DNS не совпал с тем, что вы внесли в allowlist, либо блокируется исходящий DNS.
- Решение: получите актуальный IP и добавьте правило на него, затем проверьте соединение заново.
```bash
getent hosts <эндпоинт-модели>
sudo ufw allow out 443/tcp to <полученный-ip>
sudo ufw reload
```

## Резюме и следующие шаги
Вы развернули изолированный хост, склонировали `NVIDIA/OpenShell`, запустили агента с read-only ФС, сброшенными capabilities и allowlist в исходящей сети. Дальше масштабируйте на флот: по одному контейнеру и одному `agent.env` на агента, а лицензию и поддерживаемые платформы уточните в репозитории — в анонсе они не раскрывались.

## FAQ

**Что такое NVIDIA OpenShell?**
Рантайм для безопасного и приватного выполнения флотов автономных ИИ-агентов, опубликованный NVIDIA на GitHub в организации NVIDIA по адресу github.com/NVIDIA/OpenShell. Это среда запуска, а не модель и не фреймворк для промптов.

**Какие платформы и лицензия у OpenShell?**
В исходном анонсе эти данные не раскрыты. Проверяйте файл лицензии и раздел с поддерживаемыми платформами в самом репозитории — сверьтесь с документацией перед промышленным запуском.

**Зачем запускать агентов в отдельном рантайме, а не на обычной машине?**
Автономный агент сам выбирает команды, поэтому ему нужны ограничения: non-root, read-only корневая ФС, лимиты ресурсов и allowlist в сети. Рантайм даёт границу, внутри которой агент не достанет остальную систему.

**Можно ли запустить OpenShell без Docker?**
В анонсе способ запуска не описан. Если в README нет альтернативной инструкции, используйте контейнер — это воспроизводимый и проверяемый вариант; остальное сверьтесь с документацией репозитория.