CLI¶
Публикуемая CLI-обёртка @itphx/synth умеет запускать сервер, работать с
провайдерами и общаться с моделью прямо из терминала.
Когда удобен CLI
CLI пригодится, чтобы поднять сервер одной командой, быстро спросить модель без открытия браузера или настроить провайдера на машине, где нет доступа к веб-интерфейсу.
Установка¶
После запуска откройте http://localhost:4300 и введите тот же ключ.
Запуск сервера: synth serve¶
Одна команда поднимает ядро и веб-интерфейс:
По умолчанию сервер слушает http://127.0.0.1:4300. Откройте этот адрес в
браузере и введите ключ.
Ключ API¶
Задать ключ можно любым из способов — приоритет у первого.
Ключ — это доступ
Ключ даёт доступ к вашему инстансу Synth и всем инструментам агента. Не передавайте его третьим лицам и не публикуйте в открытых репозиториях.
Основные параметры serve¶
| Параметр | Назначение |
|---|---|
--port <number> |
Порт сервера (по умолчанию 4300) |
--host <host> |
Адрес прослушивания (по умолчанию 127.0.0.1) |
--api-key <key> |
Ключ аутентификации |
--data-dir <path> |
Каталог данных (сессии, проекты, настройки) |
--home <path> |
Локальный home-каталог: конфиг и данные в одном месте |
--connect <url> |
Подключиться к корпоративному серверу (гибридный режим) |
--restart-mode <mode> |
Режим перезапуска: disabled (по умолчанию), process (поднимает внешний супервизор), supervisor (локальный dev-запуск) |
--restart-mode
Перезапуск из интерфейса (Настройки → Обслуживание) работает, только
когда режим не disabled: процесс завершается с кодом 75, а поднимает его
супервизор — systemd, Docker, Kubernetes. Флаг командной строки приоритетнее
переменной SYNTH_RESTART_MODE. Если сервис поставлен командой
synth service install, режим process уже настроен в unit — перезапускать
вручную не нужно.
Чат из терминала¶
Можно общаться с моделью, не открывая браузер.
Полезные флаги chat: --provider, --model, --agent, --api-key
(ключ провайдера) и --data-dir.
Провайдеры и модели из CLI¶
Провайдеры хранятся как JSON-файлы в каталоге данных, но управлять ими удобно
командой synth config provider.
# Локальные модели через Ollama (рекомендуемая — qwen3.8:27b).
# URL без /v1: type: ollama ходит на нативный /api/chat.
synth config provider add \
--name ollama --type ollama \
--url http://localhost:11434 \
--model qwen3.8:27b
# 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).
Опциональные — --url, --model, --api-key, --num-ctx <n>, --data-dir.
Модель по умолчанию задаётся флагом --model; выбрать модель для конкретной
сессии и проверить её доступность удобнее в разделе «Провайдеры»
веб-интерфейса.
Подробнее — Провайдеры и модели.
--num-ctx (контекстное окно Ollama)
--num-ctx <n> (целое > 0) задаёт num_ctx провайдера и есть только у
synth config provider add — подкоманды edit нет. То же значение задаётся
переменной SYNTH_PROVIDER_OLLAMA_NUM_CTX (имя провайдера в env-форме:
OLLAMA → ollama, _ → -) или полем num_ctx/numCtx в POST/PATCH/api/v2/providers(null/''— сброс). Приоритет: явныйnumCtxпровайдера >contextWindow` модели.
num_ctx передаётся в теле запроса к нативному /api/chat, где он
применяется (провайдер type: ollama всегда нормализует URL туда). Базовый
URL указывайте без суффикса /v1: старый URL с /v1 будет приведён к
/api/chat (с предупреждением в лог), а для OpenAI-совместимого пути нужен
отдельный провайдер type: openai/generic. Чтобы применить окно на стороне
Ollama, задайте его там (OLLAMA_CONTEXT_LENGTH=262144 ollama serve или
PARAMETER num_ctx в Modelfile).
Память: synth memory¶
Команда synth memory управляет индексами памяти (поиск по документам проекта
и по фактам). Это тонкий клиент: он обращается к работающему инстансу, поэтому
нужен ключ доступа.
synth memory status # готовность, провайдер, счётчики
synth memory list --scope instance # список индексов
synth memory index prj_42 --name docs --source files --filter '**/*.md' --wait
synth memory rebuild idx_7f3a --wait # пересобрать индекс
synth memory drop idx_7f3a --yes # удалить индекс
Подробнее — Память агентов.
Сервис инстанса: synth service¶
Команда synth service ставит инстанс как сервис systemd пользователя
(--user): сервис поднимается при старте машины, переживает выход из сессии и
поднимается заново после перезапуска.
synth service install # поставить сервис, включить автозапуск, запустить
synth service status # unit, автозапуск, PID, состояние health
synth service start # запустить
synth service stop # остановить
synth service restart # перезапустить
synth service enable # включить автозапуск
synth service disable # выключить автозапуск
synth service logs -f # журнал сервиса (journalctl --user -u synth)
synth service uninstall # снять unit; данные инстанса остаются
Флаг (для install) |
Назначение |
|---|---|
--port <n> / --host <addr> |
Адрес и порт инстанса |
--home <dir> / --data-dir <dir> |
Локальный home и каталог данных |
--config <path> |
Путь к config.yaml (значения по умолчанию; в unit не пишется) |
--connect <url> |
Адрес удалённого сервера (гибридный режим) |
--no-autostart / --no-start / --no-linger |
Не включать автозапуск / не запускать / не оставлять сеанс живым |
--force |
Перезаписать unit, созданный не этой командой |
--print-unit / --dry-run |
Показать unit и план, ничего не записывая |
--json |
Машиночитаемый вывод |
Только Linux + systemd
На других платформах команда сообщает о неподдерживаемости. Секреты в unit и env-файл не попадают: ключ доступа создаёт сам сервер, команда печатает путь к нему.
Подробнее — Обслуживание.
Обновление версии: synth update¶
Команда проверяет доступные версии и, по требованию, устанавливает их.
synth update --check # только проверка: что доступно
synth update --apply # установить найденную версию
synth update --channel stable # канал: auto | stable | beta
synth update --channel beta --check # что доступно в бета-канале
synth update --to 0.13.10 --apply # конкретная версия (в т.ч. откат)
synth update --registry <url> # свой реестр пакетов
synth update --dry-run # показать план без установки
| Флаг | Назначение |
|---|---|
--check |
Только проверка, ничего не устанавливать; кэш проверки игнорируется |
--apply |
Установить целевую версию |
--channel <auto\|stable\|beta> |
Канал обновлений (auto — по установленной версии) |
--to <version> |
Точная версия X.Y.Z — обновление или откат |
--registry <url> |
Реестр, переопределяющий реестр канала |
--dry-run / --json / -y, --yes |
План без установки / вывод JSON / без подтверждения |
Понижение версии
Переход с бета-канала на стабильный — это понижение версии, и он требует подтверждения. Данные при этом не откатываются: откат пакета и откат данных — разные операции.
Подробнее — Обслуживание.
Реестр MCP: synth mcp¶
Тонкий клиент к реестру MCP-серверов локального инстанса. Ключ доступа читается внутри процесса и не печатается.
synth mcp list # серверы в реестре
synth mcp add --name playwright --type http \
--url http://127.0.0.1:8931/mcp # добавить HTTP-сервер
synth mcp test playwright # проверить подключение
synth mcp reconnect playwright # переподключить после сбоя
synth mcp remove playwright # убрать из реестра
Подробнее — MCP-инструменты.
Гибридный режим¶
Чтобы работать с локальными и корпоративными проектами в одном интерфейсе, подключите локальное ядро к серверу:
После запуска войдите в интерфейс логином и паролем (или API-ключом сервера). Подробнее — Гибридный режим.