Документация.

Начало

После установки есть два входа: TUI для человека и cerberusd — демон, который держит сокет, состояние и провайдера. TUI не выполняет инструменты сам: он отправляет запрос демону и рисует поток событий.

cerberus            # TUI
cerberus status     # жив ли демон, какая модель, сколько ключей
cerberus version

Если демон ещё не поднят, TUI запускает его сам. В root-режиме сокет — /dev/socket/cerberus.sock; без root — файл в ~/.cerberus.

CLI

Один бинарь, восемь режимов. Флаг -config PATH принимает любая команда, кроме version.

Примеры

cerberus update -check
cerberus run "покажи заряд батареи и температуру"
printf '%s' "$TOKEN" | cerberus vault set API_TOKEN
echo 'rm -rf /data/local/tmp/x' | cerberus gate

status отдаёт машинный JSON — его удобно читать скриптом:

{
  "version": "1.0.0",
  "pid": 4210,
  "uid": 0,
  "uptime_sec": 1830,
  "sessions": 2,
  "provider": "gemini",
  "vault_keys": 3,
  "locked_sessions": 0,
  "redactions": 12,
  "model": "gemini-2.5-pro",
  "models": 4,
  "key_pos": 1,
  "keys": 2,
  "mirror": "/storage/emulated/0/Documents/Cerberus/.conf",
  "update_url": "https://cerberus.lain.ch"
}

TUI

Одна колонка, 32–60 символов. Команды начинаются с /; всё остальное уходит модели.

Клавиши

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

Файлы и конфигурация

Демон живёт в /data/adb/cerberus (root) или ~/.cerberus (reduced). Пользовательская копия конфига — Documents/Cerberus/.conf.

Зеркало

conf/ и Documents/Cerberus/.conf — одна и та же папка с точки зрения работы. Демон слушает inotify в обе стороны: правка в Documents сразу меняет конфиг демона, правка демона появляется в Documents. Перезапуск не нужен.

Исключение — heads/: плагины остаются на стороне демона, потому что это исполняемый Starlark, а не текст для чтения.

config.json

{
  "data_root": "/data/adb/cerberus",
  "conf_dir": "/storage/emulated/0/Documents/Cerberus/.conf",
  "socket": "/dev/socket/cerberus.sock",
  "workspace": "/data/adb/cerberus/workspace",
  "provider": {
    "kind": "gemini",
    "temperature": 0.2
  },
  "max_steps": 24,
  "tool_timeout_sec": 120,
  "allow_root": true,
  "allowed_uids": [10213],
  "update_url": "https://cerberus.lain.ch"
}

max_steps — предел шагов агента на одну задачу. tool_timeout_sec — дедлайн одного вызова. allowed_uids расширяет список тех, кому разрешён сокет: root и shell разрешены всегда, uid Termux нужно добавить явно.

.env

Файл Documents/Cerberus/.conf/.env — авторитетный источник ключей и моделей. Он же приватная копия демона; демон перечитывает его на каждое изменение.

# ключи через запятую; на 429/401 берётся следующий
GEMINI_API_KEYS=AIza...,AIza...

# это меню /model
GEMINI_API_MODELS=gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemma-3-27b-it

# выбор по умолчанию; иначе первая из списка
GEMINI_MODEL=gemini-2.5-pro

# необязательно: свой сервер обновлений
CERBERUS_UPDATE_URL=https://cerberus.lain.ch

Правила

• Ключи — через запятую, без кавычек, без пробелов вокруг. Пустые и дубликаты отбрасываются.
• GEMINI_API_MODELS — единственный источник списка в /model. Добавили строку — модель появилась.
• Gemma обрабатывается отдельно от Gemini: другой endpoint и другая форма запроса.
• Ключи никогда не пишутся в config.json и не попадают в историю: в JSON они помечены json:"-".
• CERBERUS_UPDATE_URL перекрывает update_url из конфига. Пустое значение выключает обновления.

Секреты и vault

Vault — AES-256-GCM файл vault.bin с ключом vault.key. Значения доступны только демону и только хосту: модель получает имена, но не содержимое.

cerberus vault list
printf '%s' "$TOKEN" | cerberus vault set GITHUB_TOKEN
cerberus vault rm GITHUB_TOKEN

Подстановка в HTTP

В http_request и плагинах значение подставляется на хосте из шаблона {{secret:NAME}}. Модель пишет только имя:

{
  "method": "GET",
  "url": "https://api.github.com/user",
  "headers": { "Authorization": "Bearer {{secret:GITHUB_TOKEN}}" }
}

Слепой ввод

Инструмент request_secrets просит человека ввести значения в TUI без эха. Введённое сразу уходит в vault, а модели возвращаются только имена и признак «сохранено». Так ключ не проходит через контекст модели.

Что редактируется

• read_file на .env возвращает только метаданные: имена переменных и схему, без значений.
• env_inspect показывает метаданные vault и схему .env.
• Вывод инструментов проходит через редактор: любое известное секретное значение заменяется на [REDACTED:NAME].
• Файлы vault закрыты для агента на уровне путей: чтение, запись и hard link — Deny или Block.

Периметр

Ни один вызов не доходит до ОС без вердикта chains. Скрипты разбираются парсером mvdan.cc/sh, плагины — парсером Starlark, файловые операции отображаются на зоны путей. На исполнении тот же классификатор применяется повторно к уже раскрытому argv.

Порядок вердиктов: Allow < Confirm < Deny < Block. Итог — самый высокий из найденных. При Block сессия получает SECURITY_LOCKDOWN, перестаёт отвечать и требует /unlock или Ctrl+L от человека.

Что ловится до выполнения

• Алиасы, подстановки, вложенные sh -c, su, eval и base64-пейлоады: проверяется уже раскрытая команда.
• Блочные устройства и kernel memory: /dev/block, /dev/mmcblk, /proc/kcore, /dev/mem.
• Самоодобрение: аргумент, ссылающийся на контрольный сокет, и запуск бинаря агента из агента.
• Непрозрачные скрипты: файл, который гейт не может прочитать, требует подтверждения; декодированный код — бан.
• Перезапись критических путей и rm -rf /.

Скиллы

Скилл — это процедура словами. Агент читает её через skill_read до того, как изобретать шаги. Формат — Markdown, без схемы и без кода.

Куда класть

Documents/Cerberus/.conf/skills/. Два варианта: папка с SKILL.md или один файл <имя>.md.

---
name: cleanup
---
# Очистка диска
Сначала покажи, что занимает место:
    du -sh /data/local/tmp/* | sort -h

Удаляй только *.log старше семи дней.
Никогда не трогай /data/adb/modules и vault.bin.
В конце покажи освобождённый объём.

Описание в каталоге — первая строка после frontmatter. Папка без SKILL.md, пустой файл или нечитаемый файл получают статус ошибка; /fix <имя> открывает сессию, где агент это исправляет.

Как создать вручную

• Создайте папку skills/<имя>/ и в ней SKILL.md.
• Первая строка после заголовка — короткое описание, что делает скилл.
• Пишите команды и запреты явно: агент следует тексту, а не догадывается.
• Ничего перезапускать не нужно: каталог читается при каждом /skills и каждом skill_list.

Проверка: /skills в TUI. Статусы — успешно, выключено, сон, ошибка.

MCP

MCP-сервер — обычный stdio-процесс, который объявляет инструменты. Cerberus запускает его на первом вызове и гасит через 5 минут простоя: настроенный, но неиспользуемый сервер не занимает ни CPU, ни RSS.

Формат

Папка Documents/Cerberus/.conf/mcp/<имя>/mcp.json:

{
  "command": "python3",
  "args": ["/data/data/com.termux/files/home/mcp/files/server.py"],
  "env": {
    "DATA_DIR": "/storage/emulated/0/Documents"
  },
  "disabled": false
}

Агент видит серверы через mcp_list, вызывает через mcp_call. Вывод сервера считается недоверенным текстом и проходит через тот же редактор секретов.

Как создать вручную

• Создайте mcp/<имя>/ и положите туда mcp.json и сам сервер.
• Проверьте запуск вручную: python3 server.py должен отвечать на stdio JSON-RPC.
• Откройте /mcp. успешно — сервер ответил; ошибка — причина видна рядом; сон — был запущен и уснул.
• /fix <имя> создаёт сессию для починки конфига или сервера.

Плагины

Плагин — Starlark-программа в conf/heads/<имя>/. Она исполняется в эфемерной VM, без доступа к сети напрямую: только объявленные модули. Плагины не зеркалируются в Documents.

Манифест

{
  "name": "weather",
  "version": "1.0.0",
  "description": "Текущая погода по координатам",
  "entry": "tool.star",
  "secrets": [],
  "timeout_sec": 30
}

entry по умолчанию tool.star. timeout_sec — не больше 120. secrets — имена из vault, которые плагин имеет право читать; всё остальное env.get не отдаст.

Код

def run(args):
    r = http.request(
        url = "https://api.open-meteo.com/v1/forecast?latitude=55.75&longitude=37.62&current=temperature_2m",
        method = "GET",
    )
    if r["status"] != 200:
        return {"ok": False, "status": r["status"]}
    return {"ok": True, "body": r["body"]}

def forecast(args):
    days = args.get("days", 3)
    return sys.exec(cmd = "date", timeout_sec = 5)

Верхнеуровневые функции — это и есть API плагина. plugin_list показывает список функций и признак проверки; plugin_run вызывает функцию по имени, аргументы приходят одним словарём.

Модули

Проверка и запуск

Сначала plugin_verify: статический анализ показывает функции, root-команды и найденные риски; вердикт Confirm требует согласия человека, Block банит сессию. Только после этого plugin_run. Плагин анализируется заново на каждом запуске — отметка .verified это workflow, а не граница безопасности.

Обновления

Сервер отдаёт не второй бинарь, а патч между сборками: формат CBPD1, блочное сравнение с окном 16 байт. Типичная дельта — около 20%; если изменилась только строка версии, патч весит десятки или сотни байт.

cerberus update -check     # 1.0.0 -> 1.0.1
cerberus update            # патч, sha256, замена, перезапуск

# в TUI
/check_update
/update

Что происходит

• Клиент сравнивает свою версию с /check?version=...&arch=....
• Сервер отдаёт патч на ближайшую доступную версию; если патча нет — полный файл.
• Клиент применяет патч, проверяет sha256 результата и заменяет бинарь.
• Старый файл остаётся как cerberus.old.
• Демон перезапускает себя, TUI делает re-exec уже на новый бинарь.

Сервер хранит последнюю версию и предыдущие пять, собирает патчи на каждую пару и отдаёт /latest.json, /download?arch=, /patch и /install.sh. Свой сервер задаётся через CERBERUS_UPDATE_URL.

Как это устроено

Один процесс cerberusd держит состояние; TUI — тонкий клиент. Связь — JSON-RPC по unix-сокету, поток событий вместо опроса.

Агентный цикл ограничен max_steps. Каждый шаг — ответ модели с вызовом инструмента, выполнение под гейтом и возврат результата. События шага уходят в TUI сразу, поэтому длинная команда не выглядит зависанием.

Сессии не смешиваются: /new создаёт новую, /stop отменяет текущий ход, SECURITY_LOCKDOWN помечает конкретную сессию и не даёт ей продолжаться до /unlock.

Ограничения

• Shell работает в процессе через интерпретатор, а не через системный /system/bin/sh. Переменные и cd не сохраняются между вызовами: передавайте всё одной командой или пишите скрипт.
• Плагины — Starlark, не Python и не Go. Библиотек нет, есть только модули выше.
• MCP-серверы запускаются от имени демона. Если серверу нужен root, это нужно решать внутри сервера, а не конфигом.
• В reduced-режиме нет системного shell, pm, settings, logcat и автозапуска. Песочница, файлы, HTTP, MCP, скиллы и плагины работают.
• Обновления требуют доступ к cerberus.lain.ch или своему серверу. Без сети /check_update честно покажет ошибку.