Перейти к содержанию

Локальный запуск

Локальный запуск — персональный сценарий: одна команда synth serve поднимает core и UI, агент получает прямой доступ к файлам проекта. Бэкенд, Keycloak и Kubernetes не нужны.

Когда подходит

  • Один разработчик на личной машине: быстрый старт без инфраструктуры.
  • Нужен прямой доступ к файловой системе и shell в рабочем каталоге проекта.
  • Нужны локальные модели (Ollama) или собственные ключи провайдеров.

Если нужна командная работа

Общая история, роли, OIDC и централизованный аудит появляются в Kubernetes / Helm. Если хочется оставить файлы локально, а ключи и аудит — на сервере, используйте гибридный режим.

Что поднимается

synth-ui (localhost) ←→ synth-core (:4300)

Core и UI работают в одном процессе: synth serve отдаёт и HTTP API, и статику интерфейса. Такой инстанс самодостаточен — вся логика движка, сессии и файлы остаются на вашей машине.

Что понадобится

  • Node.js >= 22 — для установки через npm и запуска из исходников.
  • pnpm >= 11 — только при установке из исходников.
  • Ollama — если планируете локальные модели (или любой OpenAI/Anthropic-совместимый API).

Установка и запуск

npm i -g @itphx/synth
synth serve --api-key my-secret-key

git clone https://gitverse.ru/itphx/synth && cd synth
pnpm install
pnpm build
node packages/synth/dist/cli.js serve --api-key my-secret-key

Откройте http://localhost:4300 и введите API-ключ.

Ключ можно не задавать

Если --api-key не указан, synth serve сгенерирует устойчивый локальный ключ, сохранит его в каталоге данных и напечатает при старте. Именно этот ключ нужно ввести в UI.

Адрес и порты

Что По умолчанию Как изменить
Адрес UI и API (core) http://127.0.0.1:4300 --port / SYNTH_CORE_PORT, --host / SYNTH_HOST
Хост прослушивания 127.0.0.1 --host / SYNTH_HOST

UI отдаётся вместе с пакетом @itphx/synth-ui и резолвится автоматически — отдельный веб-сервер поднимать не нужно.

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

Каталог данных задаётся флагом --data-dir или переменной SYNTH_DATA_DIR. Внутри лежат сессии, проекты, провайдеры, модели, агенты и секреты — ничего не уходит наружу.

Для локального инстанса удобно использовать локальный home — отдельный базовый каталог с предсказуемой раскладкой. Он задаётся флагом --home или переменной SYNTH_HOME:

<home>/
├── config.yaml       # настройки инстанса
├── data/             # сессии, проекты, провайдеры, модели
├── profiles.json     # реестр известных серверов (для гибрида)
└── credentials.json  # сохранённые учётные данные серверов

Независимые инстансы

Разные home-каталоги — это полностью независимые инстансы. Можно держать рядом локальный и гибридный запуски, не смешивая их данные.

Локальные провайдеры

Провайдер добавляется через CLI и сохраняется как JSON в каталоге данных:

# Ollama — локальные бесплатные модели
synth config provider add \
  --name ollama --type ollama \
  --url http://localhost:11434/v1 \
  --model qwen3:14b

# Любой OpenAI-совместимый API
synth config provider add \
  --name my-openai --type openai \
  --url https://api.openai.com/v1 \
  --model gpt-4o \
  --api-key sk-xxx

Обязательны --name и --type (openai, anthropic, ollama). Посмотреть список: synth config provider list, удалить: synth config provider delete <name>.

Тот же результат дают переменные окружения вида SYNTH_PROVIDER_<NAME>_*:

export SYNTH_PROVIDER_OLLAMA_URL=http://localhost:11434/v1
export SYNTH_PROVIDER_OLLAMA_MODEL=qwen3:14b
export SYNTH_PROVIDER_OLLAMA_TYPE=ollama

Подробнее — Провайдеры и модели.

Доступ к файлам и shell

Рабочий каталог задаётся у проекта. Относительные пути агент разрешает только внутри него, а файловые, shell- и git-инструменты работают напрямую с вашей машиной.

Локальный инстанс доверяет своему пользователю

API-ключ даёт полный доступ к инструментам. По умолчанию сервер слушает только 127.0.0.1 — не выставляйте его в сеть без необходимости и не публикуйте ключ.

Что дальше