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

Работа по Remote SSH

Если проект лежит на удалённой машине, а вы подключаетесь к ней по SSH, Koda работает там же — на удалённом хосте.

Главное правило: Koda работает там же, где находится проект, — то есть на удалённом хосте. Команды, чтение и запись файлов, поиск, индексация и настройки выполняются на стороне удалённого хоста.

Как это устроено

В удалённом окне VS Code держит проект и всё, что с ним связано, на удалённом хосте. Koda работает там же:

  • чтение и запись файлов происходят на удалённом хосте;
  • инструменты агента — чтение, редактирование, поиск и запуск команд — видят файлы на удалённом хосте;
  • терминал открывается на удалённом хосте;
  • индекс кодовой базы и настройки хранятся на удалённом хосте.

Koda определяет такое окружение сама и считает, что команды выполняются в Linux. Поэтому агент знает, что работает не в вашей системе, и правильно разрешает пути.

В IDE на платформе JetBrains IntelliJ удалённая работа идёт двумя путями:

  • Remote Development: бэкенд IDE запускается на удалённом хосте, а на вашем компьютере работает только клиент JetBrains;
  • IDE запущена прямо на удалённом хосте — например, через X11-проброс или VNC.

Подключиться по SSH можно из JetBrains Toolbox App, из окна приветствия IntelliJ IDEA или из JetBrains Gateway. Подключение возможно и в обратную сторону — с уже установленной IDE на сервере к вашей локальной машине.

В обоих случаях Koda работает на стороне удалённого хоста. Koda распознаёт удалённый запуск по SSH и переключает поиск по коду на запасной режим — см. раздел Поиск по коду.

Простая проверка

Попросите агента выполнить в терминале команду hostname. Если имя машины соответствует удалённому хосту, значит Koda работает на нём.

Что это значит на практике

Файлы вашего компьютера при удалённой работе Koda не затрагивает. Всё, что она делает с проектом, происходит на удалённом хосте.

Что нужно сделать

  1. Открыть проект на удалённом хосте — см. раздел Открытие проекта.
  2. Установить Koda на удалённый хост, а не только на свой компьютер — см. раздел Установка Koda.
  3. Войти в аккаунт — так же, как при обычной работе.
  4. Убедиться, что с удалённого хоста доступен api.kodacode.ru — см. раздел Сеть.
  5. При необходимости перенести свои настройки на удалённый хост — см. раздел Настройки.

Открытие проекта

Сначала убедитесь, что выполнены предварительные условия:

  1. Есть доступ к удалённому хосту по SSH.
  2. Установлено расширение Remote - SSH (ms-vscode-remote.remote-ssh).

Чтобы открыть проект на удалённом хосте:

  1. Нажмите F1 и выберите Remote-SSH: Connect to Host.
  2. Выберите хост из списка или добавьте новый (он сохранится в файле ~/.ssh/config).
  3. После подключения откройте папку проекта через меню Файл или командой Remote-SSH: Open Folder.

В левом нижнем углу окна появится индикатор SSH, подтверждающий удалённое подключение.

Работа через Remote Development:

  1. Откройте подключение к удалённому хосту из JetBrains Toolbox App, окна приветствия IntelliJ IDEA или JetBrains Gateway.
  2. В разделе SSH Connection нажмите New Connection.
  3. Укажите параметры SSH-подключения — адрес хоста, порт (по умолчанию 22), имя пользователя и способ аутентификации:
    • Password — по паролю;
    • Key pair — по паре ключей OpenSSH или PuTTY;
    • Parse config file ~/.ssh/config — использовать настройки из файла ~/.ssh/config. Нажмите Check Connection and Continue, чтобы убедиться, что подключение проходит.
  4. Выберите версию IntelliJ IDEA для загрузки на удалённый сервер. По умолчанию бэкенд ставится в каталог ~/.cache/JetBrains/RemoteDev/dist; путь можно изменить через Other options → Customize install path.
  5. Укажите путь к проекту на удалённом хосте и нажмите Upload IDE and Connect.

JetBrains Gateway скачает IDE и откроет проект в JetBrains Client.

Повторное подключение. Уже открытые проекты показаны в списке недавних — их можно открыть снова. Рядом с активным проектом отображается индикатор Running; через меню проекта можно выбрать Stop IDE Backend, чтобы остановить удалённый сеанс.

Подключение к уже запущенной IDE на сервере. Если IntelliJ IDEA уже установлена и запущена на удалённом хосте, можно подключиться к ней по сгенерированной ссылке — в разделе Connect to a Running IDE. Это подходит, если у компании свой оркестратор или удалённая IDE запускается автоматически.

Если IDE уже запущена прямо на удалённом хосте, просто откройте в ней проект — отдельное подключение не нужно.

Плагин Koda устанавливается в ту IDE, которая работает на удалённом хосте — см. раздел Установка Koda.

Установка Koda

  1. Откройте проект на удалённом хосте — как описано в разделе Открытие проекта.
  2. Откройте раздел Расширения.
  3. Найдите Koda.koda и нажмите Установить на SSH-хост.
  4. Дождитесь установки и при необходимости перезагрузите окно.

Если расширение уже стоит на вашем компьютере, VS Code обычно сам предлагает установить его и на удалённом хосте.

Установите плагин Koda на удалённый хост — в бэкенд IDE (при работе через Remote Development) или в IDE, запущенную прямо на хосте. Плагин ставится из JetBrains Marketplace так же, как любой другой.

Общая инструкция по установке — на странице Установка плагина.

Файлы, пути и терминал

Koda работает с файлами проекта напрямую, поэтому пути указываются так, как они выглядят на удалённом хосте.

  • Относительные пути (например, src/index.ts) ищутся в корне проекта.
  • Абсолютные пути (например, /home/user/project) разрешаются в файловой системе удалённого хоста.

Команды выполняются в терминале на стороне удалённого хоста.

  • Команды работают в том же окружении, что и проект, поэтому доступны все установленные на хосте утилиты.
  • Терминал Koda переиспользуется: если команда активировала виртуальное окружение или изменила переменные, это сохраняется между вызовами.
  • Команды можно останавливать — Koda прерывает их и при необходимости закрывает терминал.
  • Слишком большой вывод команды сокращается до 2000 строк или 50 КиБ, а полный текст сохраняется в файл — см. «Большой вывод инструментов».

Файлы вне проекта

Инструменты работают в первую очередь с файлами открытого проекта. Если путь ведёт за пределы проекта, Koda может его не найти.

Поиск по содержимому выполняется на стороне удалённого хоста. Koda сама проверяет, какие средства поиска доступны на хосте, и выбирает из двух вариантов:

  • ripgrep (rg) — быстрый поиск, как в локальном окружении;
  • обычный grep — запасной вариант, если ripgrep не установлен.

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

У grep нет части возможностей ripgrep: часть шаблонов поиска переводится в упрощённый вид, а очень длинные строки обрезаются. Для надёжного поиска по содержимому установите ripgrep на удалённом хосте.

Установить ripgrep на хосте на базе Debian и Ubuntu можно так:

Установка ripgrep на хосте
sudo apt-get update && sudo apt-get install -y ripgrep

Если ни ripgrep, ни grep не найдены, поиск по содержимому в проекте недоступен.

При удалённом запуске Koda распознаёт окружение по SSH и выполняет поиск по содержимому встроенным способом — обходом файлов проекта без ripgrep.

Что это значит на практике

Отдельно устанавливать ripgrep не нужно — поиск работает и без него. Но встроенный способ обхода файлов может быть медленнее ripgrep на очень больших проектах.

Поиск файлов по имени учитывает правила .gitignore и .kodaignore.

Индексация

Данные индексации хранятся на удалённом хосте, в каталоге ~/.koda/index. Поэтому индекс не переносится между вашим компьютером и удалённым хостом автоматически.

  • Впервые открыв проект на удалённом хосте, Koda построит индекс заново.
  • Индекс хранится на удалённом хосте, поэтому на вашем компьютере он не появляется.

Индексация включается на вкладке Индексация в настройках — см. Настройки индексации. Подробнее о решении проблем с индексацией — на странице Индексация.

Настройки

На удалённом хосте Koda читает настройки со стороны хоста — как если бы она была запущена в этой системе.

  • Глобальный файл config.yaml лежит в ~/.koda/config.yaml на удалённом хосте, а не в ~/.koda вашей системы.
  • Проектный файл .kodarc.json — в корне проекта на удалённом хосте.
  • Правила из файла .kodarules и игноры из .kodaignore — также в корне проекта на хосте.
  • Локальные навыки из .koda/skills, .claude/skills и .agents/skills ищутся относительно корня проекта на хосте.

Настройки у каждой стороны свои

У вашего компьютера и у удалённого хоста разные домашние каталоги, поэтому ~/.koda/config.yaml у них не общий. Настройки, сделанные на вашем компьютере, не переносятся на удалённый хост автоматически. Если настройки нужны и там, скопируйте файл конфигурации в ~/.koda удалённого хоста.

Сеть

Запросы к моделям Koda выполняет та же сторона, где работает Koda, — то есть удалённый хост.

  • С удалённого хоста должен быть доступен api.kodacode.ru.
  • Если вы используете прокси или VPN, настройте их доступность на удалённом хосте, а не только на своём компьютере.

Типичные проблемы

Koda не видит файлы проекта

Убедитесь, что Koda установлена на удалённый хост, а проект открыт на нём. Проверьте, что папка проекта действительно открыта как рабочая область.

Команды выполняются не там, где ожидается

Команды всегда выполняются на стороне удалённого хоста. Если вы ожидали команды на своём компьютере, откройте проект локально.

При удалённом запуске в JetBrains поиск выполняется встроенным обходом файлов, без ripgrep. На очень больших проектах это может занимать больше времени. В VS Code для надёжного поиска установите ripgrep или grep на удалённом хосте.

Поиск по содержимому ничего не находит

В VS Code проверьте, установлен ли ripgrep или grep на удалённом хосте. Также убедитесь, что искомый текст не исключён правилами .gitignore или .kodaignore.

Koda не отвечает

Проверьте, что с удалённого хоста есть доступ к api.kodacode.ru — см. раздел Сеть. Если вы используете прокси или VPN, они тоже должны быть доступны на хосте.