2026 DeepSeek Harness: как настроить автозапуск через launchd?

В README проекта команда для запуска MCP-варианта DeepSeek Harness указана как npx -y @deepseek-harness/mcp, то есть запуск зависит не только от самого процесса, но и от корректного окружения Node.js и npm. (github.com) Поэтому DeepSeek Harness launchd автозапуск следует строить через обычный пользовательский LaunchAgent, а не через root-сервис по умолчанию: сначала фиксируются абсолютные пути, рабочая папка, профиль и источник ключа, затем отдельно проверяются процесс, порт, модельный вызов и восстановление после сбоя.

Кому стоит читать материал:

• пользователям удалённого Mac, которым нужно автоматически возвращать DeepSeek Harness после входа или перезагрузки;
• платформенным инженерам, отвечающим за единый процесс запуска, учетную запись, журналы и остановку;
• ответственным за сдачу окружения, которым недостаточно статуса «процесс запущен» и нужен повторяемый сквозной тест.

Главная ошибка в подобных внедрениях — пытаться одним plist управлять процессами с разным жизненным циклом. Web UI должен оставаться доступным и принимать запросы, Headless-задача может завершаться после формирования результата, а автоматизация с очередью может требовать отдельного состояния, блокировок и повторной обработки. Эти сценарии нельзя считать взаимозаменяемыми.

Apple описывает LaunchAgent как процесс, работающий от имени вошедшего пользователя, тогда как LaunchDaemon работает в системном контексте и не должен зависеть от конкретной пользовательской сессии. (developer.apple.com) Для Web-рабочего процесса на удалённом Mac это важное ограничение: агент обычно лучше соответствует доступу к пользовательскому каталогу, профилю, SSH-ключам, Keychain и рабочей области.

До создания plist выполните инвентаризацию в интерактивной сессии:

whoami
pwd
command -v node
command -v npx
command -v dsh

Если одна из команд ничего не возвращает, не переносите команду запуска в launchd «как есть». Сначала выясните, каким способом установлен Node.js или CLI, где находится нужная версия, и какой именно файл запускает текущий рабочий сценарий.

Для проекта из README возможны разные формы поставки: Python-библиотека, CLI с командой dsh, npm-пакет и MCP-сервер. (github.com) В конфигурации нужно выбрать одну форму, а не смешивать npx, dsh и пользовательский shell-скрипт в одном процессе.

Если DeepSeek Harness должен работать в пользовательском Web-профиле или использовать рабочую область конкретного разработчика, начинайте с ~/Library/LaunchAgents. Apple указывает, что пользовательский агент запускается в контексте вошедшего пользователя и работает только пока эта сессия активна. (developer.apple.com) Это не недостаток, который нужно немедленно исправлять root-доступом, а часть модели безопасности и жизненного цикла.

Пример ниже намеренно не является готовым файлом для копирования. Все пути, учетные записи, идентификатор и параметры должны быть заменены после проверки конкретного Mac:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.deepseek-harness</string>

    <key>ProgramArguments</key>
    <array>
        <string>/ABSOLUTE/PATH/TO/WRAPPER</string>
        <string>--profile</string>
        <string>/ABSOLUTE/PATH/TO/PROFILE</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/ABSOLUTE/PATH/TO/WORKSPACE</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/ABSOLUTE/PATH/TO/NODE/BIN:/usr/bin:/bin</string>
        <key>DEEPSEEK_API_KEY_FILE</key>
        <string>/ABSOLUTE/PATH/TO/SECRET/REFERENCE</string>
    </dict>

    <key>StandardOutPath</key>
    <string>/ABSOLUTE/PATH/TO/LOG/stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/ABSOLUTE/PATH/TO/LOG/stderr.log</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <false/>
</dict>
</plist>

В этом шаблоне намеренно нет настоящего API Key. В README CLI-поставки используется переменная DEEPSEEK_API_KEY, но способ безопасного хранения зависит от того, как именно запускается выбранная форма Harness. (github.com) Нельзя автоматически считать, что любой режим прочитает Keychain или файл .env.

Практически безопаснее использовать wrapper, который:

1. получает секрет из заранее определённого защищённого источника;
2. экспортирует его только в окружение дочернего процесса;
3. переходит в нужный рабочий каталог;
4. запускает DeepSeek Harness по абсолютному пути;
5. не печатает окружение и аргументы в stdout или stderr.

Файл с секретом должен принадлежать нужной учетной записи, иметь минимальные права чтения и не находиться в общей рабочей папке. Root-права не решают проблему неправильной модели доступа: они лишь увеличивают последствия утечки ключа или ошибки в пути.

launchd запускает процесс не из интерактивного терминала. Поэтому не следует полагаться на .zshrc, .zprofile, менеджер версий Node.js или случайно расширенный PATH. Apple также указывает, что процесс не будет запущен, если исполняемый файл не удовлетворяет системным ограничениям запуска. (developer.apple.com)

Проверьте следующие параметры:

Создайте отдельную папку журналов и проверьте запись от имени целевого пользователя:

mkdir -p /ABSOLUTE/PATH/TO/LOG
touch /ABSOLUTE/PATH/TO/LOG/stdout.log
touch /ABSOLUTE/PATH/TO/LOG/stderr.log

Если используется npx, лучше сначала выполнить запуск вручную с тем же абсолютным путем и теми же переменными. Для постоянно работающего Web UI разумно закрепить версию пакета или использовать заранее проверенный локальный запуск, чтобы автоматический процесс не получил неожиданное обновление при очередном старте.

Не добавляйте KeepAlive на первой итерации только потому, что процесс завершился. Сначала прочитайте stderr: постоянный перезапуск может скрывать отсутствие Node.js, неверный Profile, занятую рабочую папку, ошибку API или неправильный аргумент. Apple рассматривает launchd как механизм управления жизненным циклом процессов, но он не исправляет ошибку самого приложения. (developer.apple.com)

Сохраните plist в каталоге пользователя, например:

mkdir -p "$HOME/Library/LaunchAgents"
cp /ABSOLUTE/PATH/TO/com.example.deepseek-harness.plist \
   "$HOME/Library/LaunchAgents/com.example.deepseek-harness.plist"

Перед загрузкой проверьте синтаксис и права:

plutil -lint "$HOME/Library/LaunchAgents/com.example.deepseek-harness.plist"
chmod 600 "$HOME/Library/LaunchAgents/com.example.deepseek-harness.plist"

Для управления агентами Apple рекомендует использовать launchctl; с ним выполняются загрузка, выгрузка и проверка состояния job. (support.apple.com) Конкретная команда зависит от версии macOS и выбранного режима загрузки, поэтому в рабочей инструкции фиксируйте именно ту форму команды, которая успешно прошла на целевой системе.

После загрузки проверяйте не одну строку статуса, а несколько независимых признаков:

launchctl print "gui/$(id -u)/com.example.deepseek-harness"
pgrep -af "deepseek|dsh|node"
tail -n 100 /ABSOLUTE/PATH/TO/LOG/stderr.log
tail -n 100 /ABSOLUTE/PATH/TO/LOG/stdout.log

Нужно установить:

• процесс запущен от ожидаемого пользователя;
• рабочий каталог соответствует plist;
• путь к Node.js или dsh разрешается без интерактивного shell;
• stdout и stderr сохраняются в предсказуемых файлах;
• в журнале нет реального ключа, полного окружения и чувствительных аргументов;
• завершение процесса не вызывает бесконечный цикл скрытых перезапусков.

Если процесс сразу исчезает, временно отключите автоматическое удержание и повторите запуск вручную через тот же wrapper. В первую очередь исправляются абсолютные пути, разрешения, профиль и переменные среды; только после этого оценивается политика повторного запуска.

Открытая страница Web UI доказывает только то, что некоторый процесс слушает адрес и порт. Она не подтверждает наличие Profile, доступ к рабочей области, чтение ключа или успешный вызов модели. В предыдущих проверках Web UI мы бы не смешивали эти уровни диагностики; для launchd это особенно важно, поскольку окружение после входа пользователя может отличаться от окружения в Terminal.

Для Web-режима зафиксируйте адрес прослушивания и способ доступа. Если интерфейс привязан только к 127.0.0.1, удалённый Mac не станет доступен напрямую из внешней сети; потребуется безопасный туннель или иной предусмотренный инфраструктурой канал. Не открывайте панель наружу только ради того, чтобы «проверить порт».

Для Headless-режима нельзя использовать KeepAlive как замену очереди. Если задача завершилась с ошибкой после частичного создания результата, launchd может запустить новый процесс, но не знает, на каком шаге остановилась бизнес-операция. Для возобновления нужны отдельный журнал состояния, идемпотентные файлы результатов и правило повторного запуска.

Если применяете CLI-вариант, используйте поддерживаемую команду диагностики из документации проекта, например dsh doctor, но проверяйте её в том же окружении, что и агент. (github.com) Успешная команда в вашем shell не является доказательством успешного запуска через launchd.

Тест восстановления должен состоять из отдельных испытаний, потому что у каждого свой смысл.

Остановка вручную. Остановите агент штатной командой, убедитесь, что дочерний процесс и порт исчезли, затем загрузите агент снова. Если старый процесс остался, сначала исправьте схему остановки и поиск дочерних процессов.

Аварийное завершение. Завершите основной процесс тестовым способом и наблюдайте, что происходит дальше. Если KeepAlive выключен, фиксируется ожидаемая остановка. Если включён, фиксируется факт повторного старта, но не восстановление незавершённой задачи.

Повторный вход. Выйдите из пользовательской сессии и войдите снова. LaunchAgent связан с вошедшим пользователем, поэтому этот тест показывает, возвращается ли Web UI и корректно ли создаётся новое окружение. (developer.apple.com)

Перезагрузка Mac. После перезагрузки проверьте, когда появляется процесс, отвечает ли Web UI, читается ли Profile и выполняется ли минимальная задача. Не фиксируйте выдуманное время восстановления: измеряйте его на конкретном Mac и записывайте точку отсчёта — завершение загрузки системы, вход пользователя или доступность удалённого канала.

Отдельно отмечайте, какие состояния не восстанавливаются:

• незавершённый Headless-вызов;
• временный контекст Web-сессии;
• дочерний процесс, не управляемый основным PID;
• блокировка рабочей папки;
• частично записанный результат;
• одноразовое подтверждение или ручное разрешение.

Именно здесь чаще всего появляется ложная формулировка «задача восстановилась». На самом деле восстановился только процесс. Чтобы утверждать продолжение задачи, нужно увидеть корректный итоговый артефакт или подтверждённую идемпотентную повторную обработку.

• [ ] Определён один конкретный объект: Web UI, Headless или автоматизация.
• [ ] Записаны учетная запись, абсолютный путь запуска, Profile и рабочий каталог.
• [ ] node, npx или dsh вызываются по проверенному пути.
• [ ] В plist нет настоящего API Key и других секретных значений.
• [ ] Источник DEEPSEEK_API_KEY или другой секретной переменной описан отдельно.
• [ ] Права на plist, wrapper и файл секрета проверены.
• [ ] stdout и stderr направлены в обслуживаемые журналы.
• [ ] После загрузки подтверждён владелец процесса.
• [ ] Web UI проверен отдельно от модельного вызова.
• [ ] Выполнена одна низкорисковая задача с проверкой результата.
• [ ] Для Headless-процесса записаны код выхода и путь к артефакту.
• [ ] Испытаны ручная остановка и аварийное завершение.
• [ ] Испытаны повторный вход пользователя и перезагрузка Mac.
• [ ] Зафиксировано, что именно восстанавливается, а что требует ручного вмешательства.
• [ ] Есть процедура отключения, обновления и возврата к предыдущей команде.
• [ ] После смены версии проверено отсутствие второго экземпляра и конфликта порта.

До передачи окружения подготовьте три короткие инструкции: как остановить агент, как полностью убрать его из автозапуска и как вернуть предыдущую версию.

При обновлении сначала остановите старый экземпляр, убедитесь, что порт и состояние больше не удерживаются, затем замените путь в wrapper или plist и снова выполните проверку plutil. Не меняйте одновременно исполняемый файл, рабочий каталог, Profile и источник секрета без промежуточного теста — иначе при сбое будет невозможно определить причину.

Отдельно храните:

• копию plist без секретных значений;
• версию wrapper-скрипта;
• команду ручного запуска;
• команду проверки Web UI;
• описание ожидаемого результата Headless-задачи;
• расположение журналов;
• условие, при котором требуется ручное вмешательство.

Если новая версия не проходит минимальный модельный вызов, откат должен возвращать старый абсолютный путь и прежний Profile, а не просто перезапускать тот же неисправный процесс. Одновременные экземпляры особенно опасны для Web UI: они могут конкурировать за один порт, временные файлы и состояние рабочей области.

Для дополнительной проверки удалённого сценария полезно сопоставить этот материал с руководством по приёмке DeepSeek Harness в облачном Mac-окружении, а перед передачей пользователю — с правилами доступа к удалённому Mac. Если тестовая машина не выдерживает постоянную пользовательскую сессию, отдельно оцените аренду Mac в регионе US East, но не подменяйте выбор региона предположением о доступности конкретного процесса.

Если Web UI доступен, а задача не выполняется, не начинайте с увеличения KeepAlive. Сначала проверьте рабочую папку, Profile, путь к Node.js, переменную API и stderr. Если агент работает после ручного входа, но не после перезагрузки, определите, требуется ли вошедшая пользовательская сессия. Это может быть ограничением выбранного режима, а не неисправностью launchd.

Для долгих фоновых операций зафиксируйте границу ответственности: launchd отвечает за запуск процесса, но не за бизнес-состояние задачи. Последнее должно сохраняться самим приложением или отдельным механизмом очереди. Поэтому в акте сдачи не пишите «задачи возобновляются» только на основании того, что PID появился снова.

Если DeepSeek Harness запускается на личном Mac, у текущего подхода обычно есть несколько реальных недостатков: перезагрузка зависит от ручного входа, рабочая станция может уходить в сон, обновление Node.js меняет путь запуска, а доступ к Web UI часто требует дополнительного туннеля и контроля локальной сети. При этом root-служба не устраняет эти ограничения, а добавляет риск неправильных прав и утечки ключа.

Для разового теста, отладки или короткой автоматизации локальный Mac остаётся разумным вариантом. Но если нужен предсказуемый удалённый доступ, фиксированная рабочая папка и заранее согласованная процедура восстановления, аренда Mac через JEXCLOUD может быть удобнее постоянного удержания личной машины включённой. Перед оформлением стоит сначала завершить описанный чек-лист, а затем передать в заявку не секреты, а обезличенную схему запуска, требования к пользовательской сессии и критерии успешной перезагрузки.