agentsh

Примечание для macOS: Нативная поддержка macOS через ESF (Endpoint Security Framework) + NE (Network Extension) находится в статусе Alpha. Она работает по всей цепочке — события файлов, процессов и сети проходят через системное расширение в policy-движок Go — но ожидайте шероховатостей и ломающих изменений между релизами. Для промышленного использования сегодня рекомендуем Linux.

Примечание для Windows: Мы работаем над получением подписи для minifilter-драйверов. До этого момента для промышленного использования полностью поддерживается только режим Windows WSL2.

Безопасный шлюз выполнения с применением политик для ИИ-агентов.

agentsh находится под вашим агентом/инструментарием — перехватывает действия с файлами, сетью, процессами и сигналами (включая деревья подпроцессов), применяет определённую вами политику и генерирует структурированные события аудита.

Примечание о платформах: Linux обеспечивает полное применение политик (оценка безопасности 100%). macOS ESF+NE (оценка 90%) находится в статусе Alpha — функционален, но не готов к промышленному использованию. Windows WSL2 обеспечивает полное применение политик, эквивалентное Linux (оценка 100%); нативная Windows через minifilter-драйвер + AppContainer (оценка 85%) ожидает подписания драйвера. Подробности см. в Матрице сравнения платформ.

---

Что такое agentsh?

• Готовый shell/exec endpoint, который превращает каждую команду (и её подпроцессы) в события аудита.
• Policy-движок для каждой операции: allow, deny, approve (одобрение человеком), soft_delete или redirect.
• Полная видимость ввода/вывода:
  • открытие/чтение/запись/удаление файлов
  • сетевые подключения + DNS
  • запуск/завершение процессов
  • активность PTY
  • запросы к LLM API с DLP и отслеживанием использования
  • трафик к базам данных семейства Postgres через объявленные db_services
  • отправка/блокировка сигналов (применяется на Linux, аудит на macOS/Windows)
  • запросы к базам данных через встроенный PostgreSQL-прокси — классификация и политика для каждого оператора
  • маршрутизация исходящих HTTP API-вызовов через объявленные сервисы (http_services) с правилами по методам и путям, гейтингом одобрений и принудительным контролем хостов в режиме fail-closed
• Два режима вывода:
  • вывод в терминал, удобный для человека
  • компактные JSON-ответы для агентов/инструментов

---

Зачем нужен agentsh?

В рабочих процессах агентов рано или поздно выполняется произвольный код (pip install, make test, python script.py). Традиционные механизмы контроля «запросить одобрение перед запуском команды» останавливаются на границе инструмента и не видят, что происходит внутри этой команды.

agentsh применяет политику в рантайме, поэтому скрытая работа, выполняемая подпроцессами, по-прежнему управляется, логируется и (при необходимости) требует одобрения.

---

Осмысленные блокировки: deny → redirect (суперспособность «направления»)

Большинство систем могут заблокировать действие. agentsh также может перенаправить его.

Это означает, что когда агент пробует неверный подход (или грубые обходные пути), политика может направить его на правильный путь, подменяя команду и возвращая подсказку — удерживая агента на проторенной дороге и сокращая количество бесполезных повторных попыток.

Пример: перенаправление curl на аудируемую обёртку```yaml command_rules:

• name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**Пример: перенаправление записей за пределы рабочей области обратно внутрь**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

Агент видит успешную операцию (не ошибку), но вы управляете тем, куда на самом деле всё попадает.

---

Контейнеры + agentsh: вместе лучше

Контейнеры изолируют поверхность хоста; agentsh добавляет видимость и политику во время выполнения внутри контейнера.

• Пооперационный аудит (файлы, сеть, команды) показывает, что происходило во время установок/сборок/тестов.
• Одобрения и правила действуют в долгоживущих оболочках и деревьях подпроцессов, а не только в первой команде.
• Управление на уровне путей для смонтированных рабочих областей/кэшей/учётных данных; контейнеры изначально не дают такой детализации.
• Одинаковое поведение на хосте и в контейнерах, поэтому CI и локальная разработка видят одинаковые результаты применения политик.

---

Быстрый старт

Установка

macOS (Homebrew)```bash brew tap canyonroad/tap brew install --cask agentsh

Это устанавливает пакет приложения AgentSH с системным расширением ESF+NE. После установки вам будет предложено одобрить системное расширение в **Системные настройки > Основные > Объекты входа и расширения**.

**Linux (из релиза GitHub)**

Загрузите `.deb`, `.rpm` или `.apk` для вашей платформы со [страницы релизов](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Из исходников (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Из исходников (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

См. Руководство по сборке macOS для получения подробных инструкций по сборке на macOS.

---

Запуск локально```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---
### Проверка того, что применяется

`agentsh detect` проверяет хост и сообщает, какие примитивы принуждения реально доступны — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — сгруппированные в оценки защиты по доменам, а также выбранный режим безопасности. На ограниченных хостах (Daytona, E2B, Firecracker-class), где слушатель seccomp user-notify установить невозможно, он сообщает режим, который будет *фактически* применяться, а не то, что ядро просто поддерживает.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

См. Режимы безопасности — матрицу режимов и параметры настройки.

---

Скажите агенту, чтобы он использовал это (фрагмент AGENTS.md / CLAUDE.md)```md

Shell access

• Run commands via agentsh, not directly in bash/zsh.
• Use: agentsh exec $SID -- <your-command-here>
• For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
• Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### Автозапуск (без ручного запуска демона)

Вам **не** нужно запускать `agentsh server` самостоятельно.

* Первый `agentsh exec` (или любой `/bin/sh`/`/bin/bash` с шимом) автоматически запустит локальный сервер, используя `configs/server-config.yaml` (или `AGENTSH_CONFIG`, если задан).
* Этот сервер поддерживает FUSE-слой и механизм политик активными на протяжении всей сессии; последующие команды переиспользуют его.
* Установите `AGENTSH_NO_AUTO=1`, если хотите управлять жизненным циклом сервера вручную.

---

## Использование в Docker (с шимом оболочки)