> ## 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.

# Установка и первый запуск

> Как установить Велес, создать config.json и рабочую область, проверить CLI и запустить сервер для интерфейса Велеса.

# Установка и первый запуск

Эта страница описывает базовый путь: подготовить Велес, создать рабочую область, проверить CLI и запустить сервер для интерфейса Велеса и внешних каналов.

## Что нужно понимать заранее

Для первого запуска важно знать три вещи:

* CLI-команды `veles` пока сохраняют техническое имя старого исполняемого файла;
* рабочая область хранит файлы, память и служебные данные Велеса;
* графический интерфейс подключается к серверу Велеса и показывает чат, задачи, файлы, сессии и секреты.

Велес может работать и без графического интерфейса: через CLI или каналы вроде Telegram.

## Быстрый старт Велеса

Создайте конфигурацию и рабочую область:

```bash theme={null}
veles onboard
```

Команда создаёт:

* `~/.veles/config.json` — основной файл конфигурации;
* `~/.veles/workspace` — рабочую область Велеса;
* шаблонные файлы инструкций и памяти.

Для интерактивной настройки используйте мастер:

```bash theme={null}
veles onboard --wizard
```

## Настройте модель

Минимально нужен хотя бы один LLM-провайдер и модель по умолчанию.

Пример через OpenRouter:

```json theme={null}
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-5.4"
    }
  }
}
```

Если вы используете локальную модель или OAuth-провайдера, смотрите [Провайдеры и модели](/providers_ru).

## Проверьте CLI

Одно сообщение:

```bash theme={null}
veles agent -m "Привет. Кратко проверь, что ты работаешь."
```

<Check>
  Если Велес ответил связным текстом — модель и провайдер настроены верно, можно двигаться дальше. Если появилась ошибка про ключ или модель, вернитесь к разделу «Настройте модель» и сверьтесь с [Провайдеры и модели](/providers_ru).
</Check>

Интерактивный режим:

```bash theme={null}
veles agent
```

Выход из интерактивного режима: `exit`, `quit`, `/exit`, `/quit`, `:q` или `Ctrl+D`.

Полезные параметры:

```bash theme={null}
veles agent --no-markdown
veles agent --logs
veles agent --workspace /path/to/workspace
veles agent --config ~/.veles-work/config.json
```

## Запустите сервер

Сервер нужен для интерфейса Велеса, каналов, расписаний, периодических проверок и внутренних операций с рабочей областью.

```bash theme={null}
veles gateway
```

Если в конфигурации не задан `gateway.token`, сервер не запустится. Токен нужен для авторизации интерфейса Велеса и внутренних клиентов. Вместо записи в `config.json` можно задать переменную окружения `VELES_GATEWAY_TOKEN`; она переопределит значение из файла конфигурации.

Пример:

```json theme={null}
{
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790,
    "token": "замените-на-длинный-секрет"
  }
}
```

<Check>
  Проверьте, что сервер поднялся: `curl http://127.0.0.1:18790/health` должен ответить. Тот же токен указывается в интерфейсе Велеса для подключения. Если интерфейс пишет «не подключено» — см. [Диагностику](/troubleshooting/index_ru).
</Check>

## Несколько экземпляров

Для изоляции проектов, каналов или команд используйте отдельные файлы конфигурации и рабочие области:

```bash theme={null}
veles onboard --config ~/.veles-work/config.json --workspace ~/.veles-work/workspace
veles gateway --config ~/.veles-work/config.json --port 18791
```

Важно:

* `--config` выбирает файл конфигурации и каталог служебных данных;
* рабочая область обычно берётся из `agents.defaults.workspace`;
* `--workspace` временно переопределяет рабочую область;
* если несколько серверов работают одновременно, у них должны быть разные порты.

## Docker

Базовый сценарий:

```bash theme={null}
docker compose run --rm veles-cli onboard
docker compose up -d veles-gateway
docker compose logs -f veles-gateway
```

При ручном Docker-запуске монтируйте `.veles`, чтобы сохранить конфиг и рабочую область:

```bash theme={null}
docker run -v ~/.veles:/root/.veles -p 18790:18790 veles gateway
```

## Systemd

Для постоянного Linux-запуска обычно создают user service, который вызывает:

```ini theme={null}
ExecStart=%h/.local/bin/veles gateway
Restart=always
```

Перед этим проверьте путь:

```bash theme={null}
which veles
```

## Что читать дальше

* [Конфигурация Велеса](/configuration_ru)
* [Провайдеры и модели](/providers_ru)
* [Личности](/basics/personalities_ru)
* [CLI и эксплуатация](/cli_operations_ru)
* [Интерфейс Велеса для продвинутой работы](/veles_interface_operations_ru)
* [Диагностика и частые вопросы](/troubleshooting/index_ru) — если что-то не запускается.