Конфигурация¶

Synth настраивается через переменные окружения, config.yaml и runtime-настройки в интерфейсе. Один и тот же инстанс можно запустить локально, в Docker или на сервере — от режима развёртывания зависят только значения по умолчанию.

Актуальность

Документ описывает Synth 0.8.8. Набор полей и переменных может расширяться; если сомневаетесь — сверяйтесь с актуальным config.yaml и разделами настроек в интерфейсе.

Приоритет источников¶

Значение настройки берётся из первого источника, где оно задано:

CLI-флаги  >  переменные окружения SYNTH_*  >  config.yaml  >  значения по умолчанию

CLI-флаги — высший приоритет: --port, --api-key, --data-dir, --home.
Переменные окружения SYNTH_* читаются поверх конфигурационного файла.
config.yaml находится каскадным поиском и объединяется со значениями по умолчанию (они зависят от режима: user, dev, docker, server).

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

ОсновныеUI (Vite)Провайдеры LLM

Переменная	Назначение	По умолчанию
`SYNTH_API_KEY`	Ключ доступа к API (на backend даёт роль `ADMIN`). Если не задан, `synth serve` генерирует ключ в `{dataDir}/secrets/api-key`	—
`SYNTH_DATA_DIR`	Каталог данных: сессии, проекты, провайдеры, модели	по режиму: `~/.local/share/synth`, `./data`, `/var/synth/data`
`SYNTH_WORKSPACES_ROOT`	Корень каталогов workspace проектов	`{dataDir}/workspaces`
`SYNTH_DEFAULT_WORKSPACE`	Рабочий каталог по умолчанию	`{dataDir}/workspaces/default`
`SYNTH_WORKSPACE_OUTSIDE_ROOT`	Политика workspace вне корня: `confirm` или `deny`	по режиму: standalone — `confirm`, managed — `deny`
`SYNTH_CONFIG`	Путь к `config.yaml` (приоритетнее каскадного поиска)	каскадный поиск
`SYNTH_HOME`	Базовый home-каталог локального инстанса	—
`SYNTH_HOST`	Адрес прослушивания HTTP-серверов	`0.0.0.0` (backend), `127.0.0.1` (serve)
`SYNTH_PORT`	Порт backend	`5000`
`SYNTH_CORE_PORT`	Порт core и `synth serve`	`4300`
`SYNTH_RUNNER_PORT`	Порт раннера	`5200`
`SYNTH_AUTH_DEBUG`	Режим отладки аутентификации с тестовыми пользователями	`false`
`SYNTH_DEFAULT_LANGUAGE`	Язык интерфейса backend (`ru` / `en`)	`ru`
`SYNTH_DEPLOY_MODE`	Режим развёртывания: `user`, `docker`, `server`, `dev`	автодетект
`SYNTH_LOG_DIR`	Каталог логов сервисов	существующий каталог логов
`SYNTH_BACKEND_URL`	URL backend для раннера	`http://localhost:5000`

Переменная	Назначение	По умолчанию
`VITE_BACKEND_URL`	URL backend (прокси Vite)	`http://localhost:5000`
`VITE_PORT`	Порт dev-сервера Vite	`5002`
`VITE_ALLOWED_HOSTS`	Разрешённые хосты (`true` — все)	`true`

Переменная	Назначение
`SYNTH_PROVIDER_<NAME>_URL`	URL провайдера
`SYNTH_PROVIDER_<NAME>_API_KEY`	API-ключ провайдера
`SYNTH_PROVIDER_<NAME>_MODEL`	Модель по умолчанию
`SYNTH_PROVIDER_<NAME>_TYPE`	Тип: `openai`, `anthropic`, `ollama`

<NAME> — имя провайдера в верхнем регистре. Ключи провайдеров храните в секретах и передавайте через окружение, а не в репозитории.

config.yaml¶

Каскадный поиск файла конфигурации (от высшего приоритета к низшему):

--config или SYNTH_CONFIG;
<home>/config.yaml, если задан --home / SYNTH_HOME;
./synth.config.yaml в текущем каталоге;
./config.yaml в текущем каталоге;
~/.config/synth/config.yaml;
/etc/synth/config.yaml.

Найденный файл объединяется со значениями по умолчанию, затем применяются CLI-переопределения. Ключевые секции с типовыми значениями:

server:
  host: "0.0.0.0"
  port: 5000
  corsOrigin: "http://localhost:5002"

storage:
  dataDir: "/var/synth/data"      # каталог данных вне репозитория
  workspacesRoot: ""              # пусто → {dataDir}/workspaces
  defaultWorkspace: ""            # пусто → {dataDir}/workspaces/default
  workspaceOutsideRoot: ""        # confirm | deny; пусто → по режиму

auth:
  debugMode: false                # тестовые пользователи, только для разработки
  sessionMaxAgeMinutes: 1440
  # oidc: { enabled: false, issuer: "", clientId: "", clientSecret: "", redirectUri: "" }

llm:
  defaultProvider: ""             # назначается администратором
  defaultModel: ""
  maxRetries: 3
  timeout: 60

core:
  port: 4300
  apiKey: ""                      # пусто → synth serve генерирует ключ в {dataDir}/secrets/api-key

tools:
  policy: "auto"                  # consistency | available | auto (встроенные инструменты)
mcp:
  policy: "auto"                  # consistency | available | auto (MCP-инструменты)

permission:
  rules: {}                       # allow/deny/ask для инструментов
  askTimeoutMs: 30000

security:
  protectedPaths:
    enabled: true
  secretKey: ""                   # пусто → файл {dataDir}/secrets/master.key

remote:                           # гибридный режим: локальный core + удалённый backend
  enabled: false
  backendUrl: ""
  auth:
    type: device                  # device | api_key
    apiKey: ""
    issuer: ""
    clientId: "synth"
  llm: "server"                   # server | local
  worlds: { local: true, remote: true }
  timeoutMs: 15000

Храните config.yaml с правами 600 и не коммитьте в репозиторий.

Хранилище и рабочий каталог¶

storage.dataDir — корень данных: сессии, проекты, провайдеры, модели, агенты, контекст, секреты. Пусто — каталог по умолчанию для режима развёртывания.
storage.workspacesRoot — корень каталогов проектов. Managed-проекты создают workspace внутри него (автоимя из названия проекта с суффиксом), абсолютный путь внутри корня нормализуется в относительный.
storage.defaultWorkspace — рабочий каталог сессий без проекта. Меняется без перезапуска: PUT /api/v2/settings/workspace.
storage.workspaceOutsideRoot — что делать с абсолютным workspace вне workspacesRoot: confirm — запросить подтверждение, deny — запретить. В managed-режиме политика жёстко deny и доступна только для чтения.

Секреты at-rest¶

Мастер-ключ security.secretKey шифрует секреты в хранилище (например, SSH-ключи агентов) алгоритмом AES-256-GCM.

Приоритет: переменная SYNTH_SECRET_KEY → security.secretKey в конфиге → файл {dataDir}/secrets/master.key.
Формат: base64 ровно на 32 байта либо 64 hex-символа. Иначе сервис сообщает об ошибке и не обрезает ключ молча.
Fallback-файл: если ключ не задан, core создаёт {dataDir}/secrets/master.key при первом запуске (каталог 0700, файл 0600).
Ротация: synth secrets rotate (--data-dir, --old-key, --new-key, --dry-run, --yes) перешифровывает существующие секреты. Без --yes и без --dry-run команда отказывается работать. Если эффективный ключ задан через окружение или конфиг, обновите его и там — файл при старте игнорируется. Перед ротацией сделайте бэкап данных и остановите сервис.

Гибридный режим (remote)¶

Секция remote включает подключение локального core к удалённому серверу: интерфейс объединяет локальные и удалённые проекты, а LLM-запросы можно централизовать на сервере.

Поле	Назначение	По умолчанию
`enabled`	Включить гибридный режим	`false`
`backendUrl`	Базовый URL удалённого backend	`""`
`auth.type`	Способ входа: `device` (OIDC device flow) или `api_key`	`device`
`auth.apiKey`	API-ключ для `auth.type: api_key`	`""`
`auth.issuer`	OIDC issuer (realm Keycloak) для device flow	`""`
`auth.clientId`	OIDC `client_id` (public client) для device flow	`""`
`llm`	Куда идут LLM-запросы: `server` или `local`	`server`
`worlds`	Какие миры доступны: `{ local, remote }`	оба включены
`credentialsPath`	Файл credentials; пусто → `~/.config/synth/credentials.json`	`""`
`timeoutMs`	Таймаут запросов к удалённому backend	`15000`

Отдельных переменных SYNTH_REMOTE_* нет — секция задаётся в config.yaml или CLI-флагами: synth serve --connect <url>, synth connect|disconnect, synth project publish|fork. Подробнее — в разделе Гибридный режим.