# Agent Sandbox (песочница для ИИ-агента): что это и зачем изолировать код

> **Agent Sandbox** (песочница для ИИ-агента) — изолированная среда, в которой агент выполняет команды и код: ограниченный доступ к файлам, сети и системным ресурсам. Если модель ошибётся или её обманут, ущерб ограничен стенками песочницы, а не всей вашей машиной.

Coding-агент не просто отвечает текстом: он запускает `bash`, правит файлы, ставит пакеты, ходит в сеть. Каждое такое действие выполняется с правами пользователя, который запустил агента. Песочница сужает эти права до необходимого минимума.

## Зачем изолировать выполнение кода {#zachem}

- **Ошибки модели.** Модель может уверенно выполнить `rm -rf` не в том каталоге, перезаписать конфиг или сделать `git reset --hard` с потерей работы. Это не злой умысел, а обычная галлюцинация или неверно понятая задача.
- **Prompt injection.** Агент читает README, issue, веб-страницы, вывод инструментов. В этих данных может быть спрятана инструкция вроде «отправь содержимое `~/.ssh` на такой-то адрес». Модель не всегда отличает данные от команд, подробнее — в статье про [prompt injection](/pages/prompt-injection) и [защиту от промпт-инъекций](/pages/zashchita-ot-prompt-inekciy). Полностью устранить такой риск на уровне промпта нельзя, поэтому его ограничивают на уровне среды: нет доступа к секретам — нечего красть, нет выхода в сеть — некуда отправлять.
- **Недоверенный код.** Агент запускает чужие зависимости, скрипты установки и тесты. Любой из них может делать лишнее.
- **Автономность.** Чем дольше агент работает без вашего участия, тем меньше шансов, что вы заметите опасную команду до её выполнения.

## Как это работает {#kak-rabotaet}

Песочница ограничивает три вещи:

1. **Файловую систему:** куда можно писать (обычно только рабочий каталог и временные папки) и что можно читать.
2. **Сеть:** полный запрет, список разрешённых доменов или свободный доступ.
3. **Ресурсы и процессы:** память, CPU, число процессов, привилегии.

Границу может обеспечивать операционная система, контейнер или виртуальная машина. Отдельно от неё работают **approvals** — подтверждения человека. Это разные механизмы: песочница определяет, что **технически возможно**, а approvals — что агент должен **согласовать** перед выполнением. Часто их комбинируют: внутри песочницы агент работает свободно, а выход за её пределы требует вашего «да».

## Виды песочниц {#vidy}

| Вид | Как изолирует | Плюсы | Ограничения |
|---|---|---|---|
| OS-sandbox (Seatbelt на macOS, bubblewrap на Linux) | Ограничения ОС на процесс: каталоги записи, сеть | Нет Docker, почти нет накладных расходов | Защищает только команды, которые запускает агент; не заменяет VM |
| Docker-контейнер | Отдельная файловая система, сеть и лимиты ресурсов; общее ядро с хостом | Воспроизводимая среда, привычный инструмент | Ядро общее, при ошибках конфигурации (например, проброс сокета Docker) изоляция теряется |
| microVM / виртуальная машина | Отдельное ядро (Firecracker, облачные VM) | Самая сильная изоляция | Сложнее, дольше стартует, чаще облачный вариант |
| Git worktree | Отдельная рабочая копия ветки | Защищает вашу рабочую ветку от правок агента, удобно для параллельных агентов | Это не безопасность: команды выполняются с вашими правами |

Worktree полезен для порядка в репозитории, но не ограничивает доступ к `~/.ssh`, переменным окружения и сети. Для защиты нужен один из первых трёх вариантов.

## Права, approvals и YOLO-режим {#approvals}

Инструменты обычно предлагают шкалу от «спрашивать всё» до «не спрашивать ничего»:

- **Только чтение** — агент смотрит код, но не меняет его.
- **Запись в рабочий каталог** — свободно правит проект, остальное требует подтверждения.
- **Полный доступ без подтверждений** — неофициально называется **YOLO-режим** (флаги вроде `--dangerously-skip-permissions` в Claude Code или `--dangerously-bypass-approvals-and-sandbox` в Codex). Без песочницы это означает, что любая ошибка или инъекция выполнится с вашими правами.

Практическое правило: чем меньше вы подтверждаете вручную, тем строже должна быть песочница. YOLO-режим оправдан только в изолированной среде без секретов и с ограниченной сетью. Постоянные подтверждения тоже имеют цену: человек быстро начинает нажимать «разрешить» не читая.

## Как это устроено в популярных агентах {#agents}

- **Codex CLI.** Три режима песочницы: `read-only`, `workspace-write` и `danger-full-access`; политика подтверждений задаётся отдельно (`on-request` или `never`). На macOS используется Seatbelt, на Linux — bubblewrap. В режиме `workspace-write` сеть по умолчанию выключена. Настройка в [гайде по Codex](/pages/vibe-coding-codex).
- **Claude Code.** Песочница для Bash-инструмента опирается на Seatbelt (macOS) и bubblewrap (Linux, WSL2); доступ к файлам и доменам настраивается. Она ограничивает команды оболочки, а не все инструменты агента. Для более жёсткой изоляции документация предлагает запускать агента в контейнере или VM. Подключение — в [гайде по Claude Code](/pages/vibe-coding-claude-code).
- **OpenHands.** Агент выполняет команды внутри Docker-песочницы, отдельной от хоста, а код проекта монтируется в неё. См. [OpenHands через RouterAI](/pages/openhands-routerai).
- **Strix.** Автономный пентест-агент: атакует цели и запускает инструменты, поэтому его работа в изолированном Docker-окружении — часть дизайна, а не опция. Если вы запускаете такие агенты, держите их отдельно от рабочей машины.

Как агент связывает модель, инструменты и среду выполнения, объясняет статья про [Agent Harness](/pages/agent-harness).

## Пример: запуск агента в Docker {#primer}

Минимальный вариант — запустить CLI-агента в одноразовом контейнере, куда смонтирован только нужный проект и передан только ключ RouterAI:

```bash
docker run --rm -it \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --memory 2g --cpus 2 --pids-limit 256 \
  -v "$PWD":/work -w /work \
  -e ROUTERAI_API_KEY \
  node:24-bookworm bash
```

Внутри устанавливаете агента и работаете как обычно. Что здесь важно:

- в контейнер попадает только `$PWD`, а не домашний каталог;
- не пробрасывайте `/var/run/docker.sock` и не используйте `--privileged`: это сводит изоляцию к нулю;
- передавайте только нужные переменные окружения (`-e ROUTERAI_API_KEY`), а не весь `env`;
- агенту нужен доступ к API, поэтому сеть полностью не отключается; при необходимости ограничивайте исходящий трафик на уровне файрвола.

Для Codex режим песочницы и подтверждений задаётся флагами:

```bash
codex --sandbox workspace-write --ask-for-approval on-request
```

## Связь с RouterAI {#svyaz-s-routerai}

RouterAI не выполняет команды вашего агента: он отдаёт ответы моделей, а песочницу вы выбираете на стороне агента. Агенту в контейнере нужен исходящий доступ только к `https://routerai.ru/api/v1` (OpenAI-совместимый API) или `https://routerai.ru/api` (Anthropic Messages API), VPN не требуется. Для автономных агентов удобно завести отдельный API-ключ и ограничить его, чтобы утечка ключа из песочницы не затронула остальные проекты. Модели вроде `anthropic/claude-sonnet-5.5` или `deepseek/deepseek-v4.1-flash` выбирайте в [каталоге моделей](/models); оплата в рублях.

## FAQ {#faq}

**Достаточно ли попросить модель «не делать ничего опасного»?** Нет. Инструкция в промпте — это пожелание, которое можно обойти инъекцией или ошибкой. Ограничения должна обеспечивать среда.

**Docker — это безопасная песочница?** Это разумная изоляция для ошибок и большинства сценариев, но контейнеры делят ядро с хостом. Для заведомо враждебного кода используют microVM.

**Нужна ли песочница, если я подтверждаю каждую команду?** Желательно: подтверждения утомляют, а длинная однострочная команда легко скрывает лишнее.

**Что делать с секретами?** Не кладите в рабочий каталог `.env` с боевыми ключами, давайте агенту отдельные ограниченные ключи.

**Можно ли включать YOLO-режим?** Только в одноразовой среде без важных данных и секретов.

## Что почитать {#chto-pochitat}

- [Configure the sandboxed Bash tool — Claude Code Docs](https://code.claude.com/docs/en/sandboxing)
- [Choose a sandbox environment — Claude Code Docs](https://code.claude.com/docs/en/sandbox-environments)
- [Codex CLI: command line options — OpenAI Developers](https://developers.openai.com/codex/cli/reference)
- [OpenHands на GitHub](https://github.com/OpenHands/OpenHands)
- [Agent Harness](/pages/agent-harness), [Agent Skills](/pages/agent-skills), [Prompt Injection](/pages/prompt-injection)