istok

Настройка

Переменные окружения, где хранятся данные, права на файлы, порт веб-интерфейса и резервные копии.

Istok работает с локальными настройками по умолчанию, и большинству людей менять их не нужно. Здесь перечислены переменные окружения, которые он читает, места, где он хранит данные, и то, что стоит резервно копировать.

Переменные окружения

Переменная Назначение
ISTOK_DATABASE Другой путь к базе SQLite.
ISTOK_INDEX_ROOT Другая корневая директория для данных индекса кода.
ISTOK_AGENT_ID Постоянный ID исполнителя для istok mcp.
ISTOK_AGENT_NAME Понятное человеку имя исполнителя MCP.
ISTOK_UI_PORT Порт для istok ui и istok ui service install.

Флаг командной строки важнее соответствующей переменной окружения.

Где хранятся данные

<data-home>/istok/
├── istok.db      долговременное состояние проектов (SQLite)
├── indexes/      производные данные индекса кода, по директории на проект
└── artifacts/    файлы, записанные управляемыми запусками
Система <data-home>
Linux ${XDG_DATA_HOME:-$HOME/.local/share}
macOS $HOME/Library/Application Support

Istok ничего не пишет в ваши репозитории.

База данных

В istok.db хранятся зарегистрированные проекты, задачи, контекст, знания, запуски, записи проверок, снимки контекста и связанные метаданные. Это источник истины для всего состояния Istok.

Индекс кода

Индекс каждого проекта лежит в <data-home>/istok/indexes/<project-id>/. Корень можно переопределить через ISTOK_INDEX_ROOT. Индексы — производные данные: Istok сам строит и обновляет их и может перестроить из репозитория. См. index, search и graph.

Управляемые артефакты

Содержимое артефактов хранится вне базы, в базе — только ссылки на них. С базой по умолчанию они лежат в <data-home>/istok/artifacts/; с собственным файлом базы директория артефактов находится рядом с этим файлом.

Права доступа

В Linux и macOS Istok делает базу доступной только вашему пользователю:

  • директория данных по умолчанию держится с правами 0700;
  • файл базы создаётся как обычный файл с правами 0600, а у существующего файла права выставляются в 0600 при открытии;
  • путь к базе не может быть символической ссылкой.

Эти правила касаются битов прав POSIX; существующие расширенные записи ACL не переписываются.

Своя база данных

export ISTOK_DATABASE="/path/to/istok.db"

или, для команд, которые это поддерживают:

istok mcp --database /path/to/istok.db

От базы зависит, какие проекты и какое состояние видит команда, поэтому CLI, MCP-сервер и веб-интерфейс должны использовать одну и ту же базу, чтобы видеть одно и то же. Свой путь пригодится для изолированных окружений и тестирования. Для работы через MCP нужна база в файле.

Для своего пути Istok создаёт недостающие директории с правами 0700, но не меняет права существующей директории. Если в неё могут писать группа или другие пользователи, Istok откажется её использовать: иначе другой пользователь мог бы подменить файл базы.

Порт веб-интерфейса

По умолчанию istok ui слушает 127.0.0.1:7700. Порт меняется флагом --port или так:

export ISTOK_UI_PORT=7800

istok ui service install записывает порт в файл сервиса (юнит systemd на Linux, агент launchd на macOS), поэтому последующее изменение переменной не влияет на установленный сервис, пока вы снова не выполните install. См. istok ui.

Переменные для управляемых команд

Команды, запущенные через istok run exec и istok run validate или соответствующие MCP-инструменты, получают от родительского процесса переменные из разрешённого списка, а также:

Переменная Значение
ISTOK_RUN_ID Запуск, к которому относится команда.
ISTOK_EXECUTION_ID Записываемое выполнение.
ISTOK_PROJECT_ROOT Корень репозитория проекта.

Исполнитель MCP

У каждого процесса istok mcp один исполнитель, зафиксированный при старте. Задайте его флагами или переменными окружения — это удобно, когда окружением сервера управляет MCP-клиент:

export ISTOK_AGENT_ID="codex"
export ISTOK_AGENT_NAME="Codex"
istok mcp

ID — это соглашения, а не зарезервированные значения; выберите подходящие вам, например claude для Claude Code, codex для Codex и cursor для Cursor. Без ID Istok генерирует его только для этого процесса, так что после перезапуска работа будет записана на другого исполнителя. См. Инструменты MCP.

Резервные копии

Копируйте istok.db: в нём всё долговременное состояние, включая знания. Копируйте и artifacts/, если записанные файлы для вас важны. indexes/ можно восстановить, его копировать не нужно.

istok update делает резервную копию базы, пока применяет обновление. Эта копия включает только базу, без индексов и артефактов.