> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Установка из исполняемого файла Windows

> Подготовка Veles.exe, первый запуск с отдельным config.json и обновление с сохранением рабочей области.

# Установка из исполняемого файла Windows

Распространяемая поставка состоит из `Veles.exe` и отдельного `config.json`.
Исполняемый файл содержит Велес, собранный интерфейс, Python, Node.js и необходимые
основные библиотеки. На компьютере получателя не нужно отдельно устанавливать эти средства.
Предназначено для 64-разрядной Windows 10 или 11.

## Подготовка поставки

Краткая инструкция со сборочными командами также приведена в
[основном описании проекта](https://github.com/PilgrimViis/veles#package-a-windows-executable).

На компьютере сборщика нужны 64-разрядная Windows, средство `uv` и 64-разрядный
Node.js версии 22.13 или новее вместе с `npm`. Для загрузки зависимостей нужен интернет.
В каталоге проекта выполните:

```powershell theme={null}
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\windows\build.ps1 -Preset C:\VelesPresets\config.json
```

Результат появится в `artifacts/windows`: `Veles.exe`, точная копия переданного
`config.json`, эта инструкция и контрольная сумма исполняемого файла.
Файл `build-info.json` содержит название ветки, идентификатор исходного изменения,
признак несохранённых в истории изменений, время сборки и контрольные суммы.
Он позволяет отличить поставки из разных веток. Во время сжатия программа показывает
число упакованных файлов и текущий размер архива.
Если не передать `-Preset`, сборка создаст исполняемый файл без конфигурации:
готовый `config.json` можно положить рядом позднее. Один исполняемый файл подходит
для разных заранее подготовленных конфигураций.

Для следующей версии выберите новый выходной каталог:

```powershell theme={null}
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\windows\build.ps1 -OutputDirectory artifacts\windows-next -Preset C:\VelesPresets\config.json
```

Сборка не заменяет уже существующие `Veles.exe` или `config.json` в выходном каталоге.
Она использует отдельный временный каталог внутри `.tmp`, устанавливает зависимости,
собирает текущие исходники интерфейса и упаковывает приложение. Личные рабочие области,
файлы `.env` и секреты компьютера сборщика автоматически не включаются.
Временный каталог сохраняется после завершения для разбора ошибок; его путь выводится
в окне сборки. Номера установленных библиотек Python включены в поставку.

## Первый запуск

1. Создайте доступную для записи папку, например `C:\Veles`.
2. Положите в неё `Veles.exe` и подготовленный `config.json` в кодировке UTF-8 без метки BOM.
3. Дважды нажмите `Veles.exe`. Дождитесь подготовки файлов и открытия браузера.

При первом запуске программа проверяет конфигурацию и копирует её **байт в байт**
из соседнего `config.json` в `workspace/config.json`. Она не подставляет значения
в шаблоны, не объединяет настройки и не переписывает пути в этой копии.
Поэтому `${VELES_MODEL}` и другие незаполненные обозначения из шаблонов нужно
заменить при подготовке исходной конфигурации.

Рабочая область всегда находится в `workspace` рядом с исполняемым файлом.
Даже если исходный `agents.defaults.workspace` указывает на папку сборщика,
исполняемая версия использует свою локальную рабочую область. Это переопределение
действует в памяти процесса и само по себе не изменяет скопированный файл.
Последующее сохранение настроек через интерфейс может обычным образом обновить его.

```text theme={null}
C:\Veles\
  Veles.exe
  config.json                  исходная конфигурация для первого запуска
  workspace\
    config.json                действующая конфигурация пользователя
    .veles\                    служебные данные и защищённый ключ
    secrets\                   зашифрованные секреты
    logs\                      журналы запуска
  .veles-runtime\               распакованные файлы приложения по версиям
```

Остальные каталоги рабочей области создаёт сам Велес по мере необходимости.
Интерфейс открывается по адресу `http://127.0.0.1:3080`. Сервер Велеса использует
`gateway.port` из конфигурации, обычно `18790`. Оба сервера доступны только с этого
компьютера. Порт `3080` нельзя одновременно назначить серверу Велеса.
Для остановки нажмите `Ctrl+C` в окне запуска; не закрывайте окно во время записи данных.

## Секреты и доступ к моделям

При новой установке программа создаёт ключ шифрования и сохраняет только защищённую
Windows копию в `workspace/.veles/master-key.dpapi`. Этот файл привязан к учётной
записи Windows на данном компьютере. Сам ключ передаётся серверу через
`VELES_SECRETS_MASTER_KEY` в памяти процесса, а не записывается в открытый файл.

Если `gateway.token` пуст или ссылается на локальный секрет `gateway.token`, программа
создаёт недостающий токен в зашифрованном хранилище. Заданный токен или другая ссылка
сохраняют своё значение; недоступная другая ссылка останавливает запуск.

Для поставок разным людям используйте ссылки `SecretRef`, а ключи поставщиков
моделей настраивайте отдельно через интерфейс. Ссылки на локальное хранилище сами
по себе не содержат ключей сборщика. Отсутствующие ключи моделей не мешают открыть
интерфейс, но соответствующие обращения к моделям требуют настройки.

Для конфигурации на основе `scripts/config.template.json` с моделью АЛОР задайте
`agents.defaults.model` и единственный пункт `agents.defaults.models` как
`custom/alorapi.minimax-m2.7`. В `providers.custom` укажите адрес
`https://ai.alor.ru/api`, ключ авторизации в `apiKey` и отдельный ключ в
`extraHeaders.x-upstream-token`. Ключи берутся из вашей конфигурации поставщика;
в исходники сборщика их не добавляют. Исходный шаблон при подготовке отдельной
поставки не изменяется.

Замените `gateway.token` из шаблона локальной ссылкой на секрет `gateway.token`,
чтобы новая установка создала собственный токен. Заполните или очистите остальные
обозначения `${...}`: отключённым каналам не нужны адреса и учётные записи,
а модель векторного представления можно оставить штатной
`openrouter/openai/text-embedding-3-small`. Ей, распознаванию аудио, поиску и
углублённому исследованию по-прежнему нужны отдельные настройки и ключи:
выбор модели АЛОР для чата не перенастраивает эти службы автоматически.

В локальной исполняемой поставке вход в интерфейс отключён через `NERVE_AUTH=false`.
Это параметр запуска интерфейса, а не поле `config.json`. Служебный токен шлюза
остаётся обязательным; оба сервера слушают только `127.0.0.1`.

Перенос уже заполненной рабочей области на другой компьютер отличается от новой
установки: защищённый Windows ключ нельзя просто перенести под другую учётную запись.
Нужен исходный `VELES_SECRETS_MASTER_KEY`; прежде чем удалить старую защищённую копию,
сделайте резервную копию всей рабочей области и обеспечьте сохранность исходного ключа.
Без исходного ключа существующие секреты не расшифруются. Программа не создаёт новый
ключ поверх обнаруженного зашифрованного хранилища.

## Обновление

Остановите Велес, сохраните резервную копию `workspace` и замените только `Veles.exe`.
При запуске новая версия распакует свои файлы в отдельный каталог `.veles-runtime`.
Действующий `workspace/config.json`, рабочие папки, разговоры, память и секреты
сохраняются. Новый соседний `config.json` **не применяется** к существующей установке.

Если удалить действующий файл конфигурации после первого запуска, программа
попросит восстановить его, а не подменит исходным образцом. Чтобы получить отдельную
чистую установку с другим образцом, поместите оба распространяемых файла в новую папку.
Старые каталоги приложения можно удалить из `.veles-runtime` после остановки и
проверки новой версии. Каталог `workspace` при такой очистке не удаляют.

## Ограничения и проверка поставки

Первый запуск требует места для распаковки библиотек; итоговый исполняемый файл
может быть большим. Сборка не подписывает его цифровой подписью.
Внешние службы моделей требуют подключения к сети, а дополнительные инструменты
навыков могут требовать самостоятельной установки. Необязательные зависимости
каналов Matrix и WeCom в эту поставку не входят; поддержка Exchange включена.
Не используйте встроенное обновление исходников интерфейса для этой поставки:
обновление выполняется заменой `Veles.exe`.

Перед распространением проверьте результат на чистом компьютере или в отдельной
учётной записи Windows: первый запуск, совпадение исходной и скопированной
конфигураций, настройку модели, сохранение разговора, остановку и повторный запуск.
Затем замените исполняемый файл новой сборкой и убедитесь, что пользовательские
настройки и разговор сохранились. Также проверьте запуск из папки с пробелами и
русскими буквами, сообщение о занятом порте и отказ от повторного запуска той же установки.

См. также [настройку Велеса](/configuration_ru) и [секреты](/basics/secrets_ru).