Документация

Что такое AgentMux#

AgentMux — это настольное приложение для управления ИИ-агентами для написания кода — Claude Code, Codex, Gemini CLI, OpenCode, Aider, Cursor CLI, — которые выполняются на удалённых хостах и на этом компьютере. Его основной механизм умещается в одно предложение:

Приложение поставляется одним бинарным файлом: без сервера, демона и аккаунта. Всё состояние — один файл SQLite в каталоге данных приложения. На каждый удалённый хост открывается одно мультиплексируемое SSH-соединение — терминалы, команды и передача файлов идут по его каналам, так что десять терминалов к одному хосту — это одна аутентификация. Простаивающие соединения закрываются через десять минут.

Требования#

Компьютер, на котором работает AgentMux

Управляемые хосты

• Удалённые Unix-подобные хосты (Linux / macOS): POSIX-совместимая оболочка, tmux и учётная запись SSH. Отсутствие tmux не помеха — панель установки может его установить.
• Удалённые Windows-хосты: достаточно включить OpenSSH Server. tmux там нет — сессии ведёт собственный сессионный демон AgentMux: при первом использовании он разворачивается по SFTP, а его протокол идёт через проброс порта SSH, никогда не через удалённую оболочку.
• Хосты «только экран»: машине, на которую нужно смотреть, а не работать на ней, достаточно адреса с отвечающим RDP или VNC — без SSH и без каких-либо сохранённых учётных данных (см. Работа с хостами → Хосты «только экран»).
• Этот компьютер (Linux / macOS): достаточно локального tmux — ни sshd, ни учётных данных.
• Этот компьютер (Windows): одна машина даёт два хоста — дистрибутив WSL по умолчанию (где живёт tmux) и нативный Windows (PowerShell, пути и инструментарий Windows — для сборок MSVC, WPF и запуска только что собранного .exe). Нативные сессии сохраняются собственным сессионным демоном AgentMux, так что закрытие окна не останавливает и нативную работу.

По желанию: оркестратор и семантический поиск

Локальной оркестрации и семантическому поиску по памяти требуется Ollama плюс одна чат-модель и одна модель эмбеддингов. Без Ollama всё остальное полностью работоспособно.

Установка#

Каждый выпуск содержит по одной сборке на платформу, собранной GitHub Actions из помеченного тегом коммита, с файлом .sha256 в комплекте. Сборки пока не подписаны и не нотарифицированы, поэтому первый запуск потребует одного дополнительного подтверждения — на каждой платформе своего.

macOS

1. Скачайте agentmux-macos-universal.zip, распакуйте и перетащите AgentMux.app в «Программы».
2. Обработайте предупреждение о неподписанной сборке в зависимости от версии macOS (таблица ниже).
3. После этого приложение открывается как обычно.

Windows

1. Скачайте и распакуйте agentmux-windows-amd64.zip — внутри agentmux.exe и скрипт установки.
2. Запустите двойным щелчком; когда появится SmartScreen, выберите Подробнее → Выполнить в любом случае.
3. Для полноценной установки (в %LOCALAPPDATA%\Programs\AgentMux, с ярлыками на рабочем столе и в меню «Пуск», без прав администратора) выполните из распакованной папки:

powershell -ExecutionPolicy Bypass -File install-windows.ps1

Тот же скрипт с параметром -Uninstall отменяет установку, не трогая данные в %APPDATA%\AgentMux.

Linux

1. Сначала установите зависимость времени выполнения: sudo apt install libwebkit2gtk-4.1-0 в Debian/Ubuntu, sudo dnf install webkit2gtk4.1 в Fedora.
2. Скачайте и распакуйте agentmux-linux-amd64.tar.gz — бинарный файл, значок, .desktop-запись и install.sh.
3. Запустите ./install.sh или сам бинарный файл напрямую.

Проверка загруженных файлов

# к каждому файлу прилагается .sha256:
shasum -a 256 -c agentmux-macos-universal.zip.sha256   # macOS
sha256sum -c agentmux-linux-amd64.tar.gz.sha256        # Linux

Серверная сборка (headless)

У того же приложения есть полностью статичная headless-сборка: agentmux-server-linux-amd64.tar.gz и agentmux-server-linux-arm64.tar.gz. Она не линкует GTK и webview и не требует дисплея — запустите её на любом Linux-сервере, и она отдаст полноценное веб-приложение. Рекомендуемый способ развёртывания — установочный скрипт одной строкой (с сервисом systemd и самообновлением): см. раздел Headless-сервер.

Android

1. Скачайте agentmux-android.apk (Android 8.0+ · arm64) и установите на телефон или планшет — потребуется разрешить установку из неизвестных источников.
2. При первом запуске foreground-сервис поднимает встроенное ядро, а WebView подключается к 127.0.0.1. Никакой сервер не нужен.
3. Если в репозитории настроены ключи подписи, APK выходит подписанным и обновляется поверх; иначе он собирается с debug-подписью — установить его можно, но перед сменой подписи старую версию нужно удалить.

Быстрый старт#

Четыре шага до первого управляемого агента. Всё описанное здесь доступно и через палитру команд Ctrl/⌘ K — самый быстрый путь к любому действию.

Шаг 1. Добавьте хост

Удалённому хосту нужны три вещи:

• Адрес и пользователь — те же, что и в ssh user@host.
• Один из трёх способов аутентификации: ssh-agent (рекомендуется — заполнять ничего не нужно), файл ключа (парольная фраза поддерживается) или пароль.
• Jump-хосты (по желанию) — для окружений за бастионом.

Этому компьютеру не нужно ничего, кроме имени — ни sshd, ни учётных данных. В Windows вы увидите два локальных хоста: дистрибутив WSL и нативный Windows. Выбирайте по задаче: Unix-инструментарий — в WSL, MSVC/WPF — в нативный.

Шаг 2. Добавьте проект и рабочую область

Рабочая область — это рабочий каталог на хосте (обычно корень репозитория). Добавить её можно двумя способами:

• Через форму: выберите хост, введите путь.
• Через файловый браузер (быстрее): откройте файлы хоста, найдите каталог и «добавьте как проект» прямо на месте — его имя, путь и хост уже известны.

Шаг 3. Добавьте агента и запустите его

Агент — это имя плюс команда запуска, та же самая, что вы набрали бы в терминале:

# типичные команды запуска, настройте под себя
claude                    # Claude Code
codex                     # OpenAI Codex CLI
gemini                    # Gemini CLI
aider --model sonnet      # Aider
opencode                  # OpenCode

Нажмите Start — и агент уже работает внутри tmux на хосте. API-ключи агента настраиваются на стороне хоста (в конфигурации самого агента или его окружении) — AgentMux их не читает и не проксирует.

Шаг 4. Подключитесь и работайте

Щёлкните по агенту или найдите его по имени через Ctrl/⌘ K. Перед вами настоящий терминал — цвет, мышь, выделение, поиск. Вмешивайтесь и печатайте в любой момент, корректируйте курс агента, возвращайте ему управление — без перезапуска. Боковая панель даёт Start / Stop / Restart / Attach, состояние процесса и последний вывод.

Стена терминалов#

Область терминала делится максимум на девять панелей (3×3), каждая со своей сессией — на одном хосте или на нескольких, и каждая интерактивна независимо:

• Добавить панель: Ctrl/⌘ \. Если есть свободная открытая вкладка, разделение происходит мгновенно; иначе диалог предложит хосты, каталоги рабочих областей, запущенных агентов и открытые вкладки.
• Раскладка адаптируется: панели делят область в пропорциях, а не в пикселях. Слишком узкая для чтения колонка убирается, поэтому в суженном окне стена 3×3 переливается в более высокую сетку, а не в девять щелей.
• Перетаскивайте разделители, чтобы менять размер панелей.
• Временное увеличение: двойной щелчок по вкладке панели (или Ctrl/⌘ ⇧ ↵) разворачивает её на всю область; повторно — возвращает обратно. Разбивка под ней не меняется.
• Панель — это вид, а не сессия: закрытие панели (Ctrl/⌘ ⇧ \) скрывает терминал, но вкладка и её оболочка остаются подключёнными. Количество панелей восстанавливается при следующем запуске.

Горячие клавиши#

Рассылка и подтверждения#

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

• Выбор по проекту, по хосту или отметкой отдельных агентов.
• Статус доставки по каждому агенту; неудачные доставки заметны сразу и повторяются по отдельности.
• Типичные применения: приостановить весь парк, ввести новое требование («с этого момента все сообщения коммитов — на английском»), опросить прогресс по всем агентам.

Работа с хостами#

Панель установки: подготовка нового хоста

Панель установки сначала обследует хост и предлагает только те агентские CLI и среды выполнения, которые он реально поддерживает, объясняя, почему остальные недоступны. Установка идёт внутри tmux, поэтому оборванное соединение не оставит наполовину установленных пакетов. Сам tmux, если его нет, тоже устанавливается отсюда.

Установка в один клик охватывает агентские CLI — Claude Code, Codex, Gemini CLI, Grok CLI, OpenCode, Aider, Cursor CLI — и среды выполнения, включая Node, Python, tmux, Docker и Ollama. Для Docker предусмотрено шесть способов (сначала официальный скрипт, затем пакеты самих дистрибутивов, на macOS — Docker Desktop через Homebrew) с повтором через зеркало там, где этого требует сеть. После установки движка запускается демон, пользователь добавляется в группу docker, и об этом сообщается прямо: чтобы группа вступила в силу, нужен новый вход в систему.

Телеметрия хоста

Метрики по каждому хосту собираются одной командой:

• CPU по режимам и по ядрам, память, нагрузка
• Использование диска и пропускная способность, сеть, файловые дескрипторы
• Загрузка NVIDIA GPU, если он есть

SFTP-браузер и редактор

Доступ к файлам идёт по тому же SSH-соединению. Запись атомарна и сопровождается проверкой изменений: если агент, работающий в том же каталоге, изменил файл, сохранение будет отклонено вместо тихой перезаписи — сначала посмотрите, что изменилось, а потом решайте.

Удалённый рабочий стол (встроенный клиент RDP / VNC)

Иногда работа — это экран: установщик, который требует окна, GUI-тест, машина, на которую кто-то должен посмотреть. Правый клик по хосту, открыть рабочий стол — и три обычных порта, 3389 (RDP) и 5900 / 5901 (VNC), опрашиваются одновременно, и намеренно ничего сверх них: инструмент, по собственной инициативе сканирующий порты чужих машин, — не тот инструмент. На SSH-хосте запрос идёт через то самое SSH-соединение, которое у хоста уже есть, поэтому рабочему столу, слушающему только петлю, ничего не нужно открывать наружу, и второй набор учётных данных не требуется.

• Клиент живёт внутри приложения: рабочий стол открывается вкладкой в области терминала, рядом с вашими панелями. Это настоящий клиент протокола, а не его картинка — noVNC для VNC и IronRDP, скомпилированный в WebAssembly, для RDP — и загружается он по требованию: кто никогда не открывает рабочий стол, не платит за него ни байта. Разрешение удалённого экрана следует за размером панели.
• Раз клиент внутри приложения, возможность есть на каждом клиенте — в настольном приложении, браузере, на планшете и телефоне — и больше не зависит от того, что окажется установлено локально.
• Учётные данные для входа вводятся при открытии сессии, доставляются хосту по его существующему каналу и нигде не хранятся.
• Когда Windows отказывает во входе, вы видите не NT-код состояния, а то, в чём именно отказано: учётная запись заблокирована (и на сколько), пароль истёк, учётная запись отключена, пользователь не в группе «Пользователи удалённого рабочего стола», ограничение по часам входа, отсутствующий префикс домена — типичные причины переводятся на человеческий язык, каждая со способом исправления.
• Настольное приложение по-прежнему предлагает вариант «системный клиент»: ответивший порт пробрасывается на петлю этого компьютера и передаётся тому клиенту, который здесь есть — mstsc в Windows, «Общий экран» в macOS, Remmina или FreeRDP в Linux. Проброс закрывается сам через пять минут после ухода последнего клиента, освобождая аренду SSH; если ни одного клиента не установлено, он остаётся поднятым, а его адрес сообщается.
• Какой рабочий стол отдаёт хост, запоминается — только конечные точки, которые действительно ответили, и никогда порт, набранный по ошибке, — поэтому во второй раз вопросов не будет. Эта память принадлежит хосту, а не установке, поэтому она путешествует вместе с экспортом конфигурации.

Хосты «только экран»

Желание смотреть на машину и желание работать на ней — разные потребности. Тип хоста «Удалённый рабочий стол» служит первой: имя, адрес и операционная система — она определяет протокол (RDP для Windows, VNC для macOS / Linux) и подсказывает порт, и то и другое можно изменить. Поля учётных данных нет вовсе: всё, что спросит сам рабочий стол, вводится при открытии сессии и нигде не хранится.

• В дереве это ровно экран: без терминала, без агентов, без рабочих областей, никогда не кандидат в jump-хосты и без места в пуле SSH-соединений — ничто, чему нужна оболочка, не предложит его в этом качестве.
• Соединение идёт напрямую на его порт рабочего стола, как это сделал бы любой обычный клиент удалённого рабочего стола; «Проверить соединение» набирает этот порт и сообщает задержку.
• Превращение в машину, на которой можно работать: панель деталей такого хоста заодно проверяет порт 22. Если SSH отвечает, кнопка «Добавить как SSH-хост» открывает диалог хоста с уже заполненным адресом — создаётся новый, полноценный хост, а строка «только экран» остаётся как была. Если SSH не отвечает, а система — Windows, панель показывает точную команду PowerShell, включающую OpenSSH Server, с копированием в один клик: вставьте её в уже открытую панель рабочего стола, выполните там и нажмите «обновить».
• С включённым OpenSSH добавьте машину как хост «Удалённый Windows» — и агенты работают нативно: PowerShell, MSVC, WPF — под присмотром сессионного демона AgentMux, так что закрытие окна ничего не останавливает. С этого момента машина — и экран, и место для работы.

Из чего состоит хост

Панель метрик теперь отвечает не только на вопрос, чем машина занята, но и на вопрос, что она такое: модель процессора, характеристики модулей памяти, физические диски и видеоадаптеры. Это статические сведения, поэтому они читаются один раз и кешируются на сессию, а не идут через трёхсекундный опрос.

Headless-сервер#

Ядро AgentMux умеет работать без окна: полностью статичная headless-сборка, не линкующая ни GTK, ни webview, отдаёт полноценное веб-приложение с любого Linux-сервера — терминалы, агенты, рассылка, файловый браузер, удалённый рабочий стол; тот же набор возможностей, что и у настольной сборки, а не урезанный вид. Настольное приложение, телефоны, планшеты и любой браузер подключаются к нему и видят один набор хостов и один набор работающих сессий.

Установка одной строкой (рекомендуется)

curl -fsSL https://raw.githubusercontent.com/tan-zhuo/AgentMux/main/scripts/install-server.sh | bash

Скрипт делает всё на Linux-сервере (amd64 / arm64), целиком от имени вызвавшего пользователя — root не нужен:

• Скачивает серверную сборку под текущую архитектуру, сверяет .sha256 и устанавливает в ~/.local/bin — сначала новый файл, затем атомарное переименование, так что половины бинарного файла не бывает никогда.
• Регистрирует пользовательский сервис systemd (~/.config/systemd/user/agentmux.service, с перезапуском при сбое) и включает lingering — сервис продолжает работать после отключения и выхода из системы. Машины без systemd откатываются на nohup плюс crontab с @reboot.
• Включает HTTPS по умолчанию (самоподписанный сертификат), слушая :8642.
• Проверяет сервер и объявляет об успехе только когда тот действительно отвечает; если он не поднялся, вам печатаются нужные строки журнала сервиса и самая частая причина (занятый порт — выберите другой через --addr).
• По завершении печатает три вещи, нужные клиенту: адрес, токен доступа и отпечаток сертификата.

Основные параметры (после bash -s -- при запуске через конвейер):

Запуск вручную

# серверная сборка (agentmux-server-linux-*): запустить — значит раздавать; :8642, по умолчанию обычный HTTP
./agentmux

# с параметрами: все интерфейсы, самоподписанный HTTPS
./agentmux --addr 0.0.0.0:8642 --tls

# десктопный бинарный файл входит в тот же режим
agentmux --serve --addr 0.0.0.0:8642 --tls

При первом запуске в лог печатается токен доступа (48 шестнадцатеричных символов; он же сохраняется как serve-token в каталоге данных с правами 0600), а при включённом TLS — строка с отпечатком сертификата SHA-256: именно её сверяет каждый клиент при подключении.

Шифрование и доверие: самоподписанный сертификат, закреплённый по отпечатку

За самоподписанный сертификат не ручается ни один CA, поэтому каждое устройство само решает, кому верить: при первом подключении клиент получает сертификат, показывает его отпечаток SHA-256, и вы сверяете его со строкой в журнале сервера, прежде чем подтвердить. С этого момента устройство принимает ровно этот сертификат — без имён и сроков действия; изменившийся отпечаток — это отклонённое соединение. Смените адрес на настоящий CA-сертификат — и закрепление само уступит место обычной проверке. Каждое значение, которое нужно перенести, — токен, адрес, отпечаток — снабжено копированием в один клик: они для буфера обмена, а не для глаз.

Ограничения: серверная сборка публикуется только для Linux (amd64 / arm64). Чтобы раздавать с macOS или Windows, используйте режим сервера настольного приложения или соберите свою: go build -tags headless.

Переключение ядра и режим сервера#

За каждым окном AgentMux стоит ядро — та часть, что держит конфигурацию хостов, SSH-соединения, ключи и всё состояние. По умолчанию окно смотрит на ядро этого устройства, но эти двое разделимы: окно может смотреть на ядро другой машины, а ядро этого устройства можно открыть для других устройств. Эти два направления — две соседние страницы в настройках.

Направить окно на удалённое ядро (Настройки → Подключение)

1. Выберите «Удалённый сервер» и введите адрес экземпляра serve, например https://192.168.1.10:8642.
2. При самоподписанном HTTPS появится карточка с отпечатком: сверьте его с журналом сервера (или со страницей режима сервера на той машине) и подтвердите — «отпечаток совпадает, доверять и подключиться».
3. Один раз введите токен доступа той машины — и окно переключается.

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

• Рекомендуемая схема: ядро работает на одном настольном компьютере или сервере локальной сети (headless-сборка либо режим сервера), а ноутбук, телефон и планшет указывают на него — SSH-ключи и jump-хосты настраиваются один раз, на той единственной машине, и каждое устройство видит одни и те же хосты и одни и те же работающие терминалы.
• Домой вернуться можно всегда: когда удалённая сторона недоступна, пустого окна не будет — страница ошибки объясняет, что именно не удалось, с кнопками «Повторить» и «Вернуться на это устройство».
• В приложении для Android та же страница «Настройки → Подключение»: по умолчанию оно использует встроенное в устройство ядро, но может указывать и на удалённый экземпляр.

Сделать этот компьютер сервером (Настройки → Режим сервера)

Обратное направление: настольное приложение само принимает подключения других устройств — ничего дополнительно ставить не нужно:

1. Настройки → Режим сервера; проверьте адрес прослушивания — :8642 по умолчанию слушает все интерфейсы, 127.0.0.1:8642 ограничивает доступ этой машиной.
2. «Шифрование (HTTPS, самоподписанный сертификат)» включено по умолчанию; нажмите «Включить».
3. Страница покажет адреса подключения, токен доступа и отпечаток сертификата — каждый с копированием в один клик. В приложении на телефоне откройте «Настройки → Подключение», введите адрес, вставьте токен, сверьте отпечаток.

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

Планшет и телефон#

Любой современный браузер открывает полноценное приложение — планшет на Android, iPad, телефон. Терминалы, агенты, набор инструментов, файловый браузер и удалённый рабочий стол работают полностью; это не режим «только чтение».

К чему подключаться

Поднимите сервер, как описано в разделе Headless-сервер (одна строка на Linux-машине), или включите режим сервера в настольном приложении. Обе дороги дают одни и те же три вещи: адрес, токен доступа и отпечаток сертификата.

Открыть на планшете

1. Откройте в браузере https://хост:8642 (с самоподписанным сертификатом браузер один раз спросит на странице предупреждения; при развёртывании без TLS адрес начинается с http://).
2. Один раз введите токен — дальше его хранит браузер.
3. iPad: в Safari «Поделиться → На экран «Домой»». Android: в Chrome «Добавить на главный экран». После этого приложение работает отдельно, без адресной строки.

Закрытие браузера ничего не останавливает — ровно как закрытие окна на десктопе: агенты живут в удалённом tmux.

Приложение для Android

К каждому выпуску приложен agentmux-android.apk (Android 8.0+ · arm64). Он идёт на шаг дальше описанного выше: в нём встроено то же ядро, что и в серверной сборке, оно запускается на устройстве foreground-сервисом, а WebView подключается к нему на 127.0.0.1. SSH идёт прямо с телефона или планшета, конфигурация и ключи остаются на устройстве — постоянно включённая машина не нужна.

• Foreground-сервис здесь принципиален: без него Android замораживает процесс при блокировке экрана и обрывает все SSH-соединения. Поэтому в шторке висит постоянное уведомление.
• Сами агенты живут в удалённом tmux, поэтому даже если система выгрузит приложение, на них это не повлияет — при повторном открытии оно переподключится.
• Удалённый режим: страница «Настройки → Подключение» в приложении может направить его на экземпляр serve вместо встроенного ядра. При самоподписанном HTTPS приложение получает сертификат и показывает карточку с отпечатком — сверьте его с журналом сервера и подтвердите; с этого момента устройство принимает ровно этот сертификат.
• Известное ограничение: при подключении к серверу с самоподписанным сертификатом, закреплённым по отпечатку, клиент удалённого рабочего стола недоступен (WebView в Android не передаёт приложению на рассмотрение ошибки сертификата в WebSocket). Терминалы и всё остальное не затронуты; настоящий CA-сертификат снимает ограничение.

Раскладка, переделанная под большой палец

• Уже с 768px боковые панели становятся выдвижными поверх содержимого — по одной за раз, с закрытием при выборе вкладки.
• Место строки состояния занимает нижняя панель навигации: дерево, палитра команд, панель деталей и настройки — подписанные кнопки высотой под палец, с учётом безопасной зоны.
• Диалоги и палитра команд перестают настаивать на десктопных отступах там, где для них нет места.

Оркестратор и Ollama#

Оркестратор — это операционный помощник на локальной модели: дайте ему цель (например, «выясни, почему agent-3 перестал продвигаться») — и он изучит состояние парка, поднимет прошлый контекст и будет двигаться по одному вызову инструмента за раз. Он выключен, пока вы его не включите.

Предварительные условия

1. Установите Ollama и держите его запущенным.
2. Загрузите одну чат-модель и одну модель эмбеддингов, например:

ollama pull qwen3             # чат-модель (пример — выбирайте под своё железо)
ollama pull nomic-embed-text  # модель эмбеддингов, используется для семантического поиска

Процесс одобрения

• Каждая операция, изменяющая хост, ждёт вашего явного одобрения. Карточка одобрения показывает инструмент, его полные аргументы, целевой хост и обоснование, приведённое моделью.
• Разрушительные операции подтверждаются на любом хосте, независимо от уровня доверия к нему.
• Инструменты — фиксированный белый список, каждому уровень риска присвоен при объявлении раз и навсегда. Выполнение проходит единый шлюз: уровень риска × степень доверия к хосту × то, что запустило прогон.
• Вывод с удалённых хостов попадает в модель с пометкой «данные»; текст, похожий на инструкции, помечается флагом на карточке одобрения и в журнале решений (защита от инъекций промптов).
• Каждый шаг каждого прогона записывается — включая предложения, которые были отклонены или остались без ответа.

Плановые обходы

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

Навыки и память

• Навыки: переиспользуемые процедуры — условия применения, шаги, инструменты, ограничения — автоматически подбираются, когда эти условия повторяются. Навыки, предложенные оркестратором, попадают в очередь на проверку и не действуют до одобрения.
• Память: факты о проектах, высказанные предпочтения и активность агентов индексируются для поиска по формулировке или по смыслу. Эмбеддинги вычисляются локально; ничего не покидает машину. Учётные данные, совпадающие с известными шаблонами, вымарываются до сохранения.

Семантика жизненного цикла#

Усвойте эти правила — и момента «я что, только что потерял задачу?» у вас не будет никогда:

Агенты, которые ждут человека

Агент, задавший вопрос, агент, закончивший работу с результатами на проверку, и агент, простаивающий у приглашения без задачи, — раньше в дереве все они выглядели как «running». Теперь опрос читает каждую панель и классифицирует её, поднимая устойчивую отметку на тех переходах, которые должен увидеть человек, и снимая её, когда кто-то действительно посмотрел: открыл терминал, ответил или закрыл отметку вручную.

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

Переподключение после обрыва

Терминал, потерявший транспорт, — это ещё не конец: сессия tmux на той стороне работает, агент внутри неё продолжает трудиться, сломался только канал. Поэтому канал восстанавливается — тот же идентификатор shell, тот же буфер прокрутки, та же панель — с задержкой, растущей от секунды до пятнадцати, и отказом примерно через пять минут, когда остаётся прежняя кнопка ручного переподключения.

• Сессию, завершившуюся по собственной воле, не трогают: код выхода — это решение, а не сбой.
• Два keepalive отвечают на разные вопросы. TCP keepalive не даёт промежуточным устройствам забыть простаивающий поток; SSH-keepalive доказывает, что дальняя сторона ещё отвечает, и считает пинг неудачным через десять секунд.
• Однократные командные терминалы исключены. Перезвонить означало бы выполнить команду заново, а перезапуск установки из-за моргнувшего Wi-Fi — побочный эффект, о котором никто не просил.

Обновления и перенос#

Проверка обновлений и установка в один клик

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

• Обновление скачивает нужный для платформы файл с индикатором прогресса, проверяет опубликованный sha256, заменяет работающий исполняемый файл (на macOS — весь bundle; на Windows работающую программу удалить нельзя, поэтому она переименовывается в сторону), перезапускается и убирает остатки при следующем старте.
• Неудачная замена откатывается к той сборке, которая работала.
• Сборка для разработки никогда не перезаписывается — она обновляется через git, и диалог настроек прямо об этом говорит.

Перенос установки на другую машину

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

• Шифрование. Файл запечатывается парольной фразой, а не мастер-ключом этой машины: ключ лежит в связке ключей этого компьютера и не может путешествовать, так что копия базы на той стороне была бы нечитаемой. Argon2id превращает фразу в ключ, AES-256-GCM запечатывает содержимое. Параметры стоимости обязаны ехать открытым текстом, чтобы файл вообще можно было открыть, поэтому они аутентифицированы, а не спрятаны: заголовок, переписанный на что-нибудь дешёвое, не ослабляет файл, а перестаёт его открывать.
• SSH-пароли и парольные фразы ключей едут только по запросу, существуют в открытом виде ровно столько, сколько нужно для запечатывания, и по прибытии заново запечатываются под собственным мастер-ключом новой машины.
• Импорт никогда не перезаписывает. Хост по тому же адресу, проект с тем же именем, путь на той же машине — каждый остаётся как есть, а всё, что указывало на него в файле, начинает указывать на уже имеющуюся копию. Поэтому импорт одного и того же файла дважды ничего не добавляет, а попытка импорта ничего не стоит. О том, что перенести не удалось, сообщается прямо: файл ключа, которого нет на этой машине, промежуточный хост, который не поехал, уже занятое здесь имя сессии.
• Две вещи намеренно остаются на месте. Раскладка терминалов и состояние агентов описывают именно эту установку, а не конфигурацию; а разрешение оркестратору действовать принимается на каждой машине отдельно — файл, пришедший откуда-то ещё, таким решением не является.

Сборка из исходников#

Go 1.25+ и Node 20+. Сначала собирается фронтенд (он встраивается в бинарный файл), затем Go:

git clone git@github.com:tan-zhuo/AgentMux.git
cd AgentMux
cd frontend && npm install && npm run build && cd ..
go build -o agentmux .
./agentmux

Linux требует заголовков WebKitGTK и тега сборки gtk3:

sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go build -tags gtk3 -o agentmux .

Windows — для GUI-файла, запускаемого двойным щелчком, без консольного окна:

go build -ldflags "-H windowsgui" -o agentmux.exe .

Подробности (тестирование, подготовка выпуска) — в docs/development.md.

Устранение неполадок#

macOS сообщает, что приложение «повреждено», или не открывает его

Это обычная преграда для неподписанных сборок, а не повреждение файла. Следуйте таблице в разделе «Установка» или исправьте одной командой: xattr -dr com.apple.quarantine /Applications/AgentMux.app.

Linux не запускается / не хватает библиотеки

Почти всегда дело в рантайме WebKitGTK. Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-0; Fedora: sudo dnf install webkit2gtk4.1.

Windows: окно вообще не появляется

У GUI-сборок нет консоли для вывода ошибок. Загляните в startup-error.log в каталоге данных (%APPDATA%\AgentMux) — настоящая причина сбоя записана там.

«Host key mismatch» при подключении

Ключ хоста отличается от закреплённого при первом подключении. Сначала выясните почему: переустановленный хост или переназначенный IP — это нормально; удалите запись хоста и добавьте её заново. Если же ничего меняться не должно было, рассматривайте это как возможную атаку «человек посередине» и сверьте отпечаток ключа по независимому каналу.

Строка состояния сообщает, что системное хранилище недоступно

Мастер-ключ шифрования обычно хранится в системном хранилище (Keychain / Диспетчер учётных данных / Secret Service). Там, где хранилища нет (обычное дело на минималистичных рабочих столах Linux), AgentMux переключается на файл с правами 0600 и сообщает об этом в строке состояния. Ничего не ломается; чтобы вернуть хранение в системном хранилище на Linux, установите и включите gnome-keyring или другую реализацию Secret Service.

На целевом хосте нет tmux

Откройте панель установки этого хоста — tmux есть в списке, и AgentMux установит его подходящим пакетным менеджером.

Оркестратор / семантический поиск недоступны

Убедитесь, что Ollama запущен (ollama list показывает ваши модели) и что загружены и чат-модель, и модель эмбеддингов. Без Ollama эти две функции остаются выключенными; всё остальное не затронуто.

Где мои данные?

Всё состояние — один файл SQLite в каталоге данных приложения (%APPDATA%\AgentMux в Windows). Резервная копия этого каталога — резервная копия всего; удалите его для полного сброса. Учётные данные хранятся зашифрованными AES-256-GCM, а ключ — в системном хранилище ОС.

Планшет не открывает хост:8642

• Проверьте схему: установочный скрипт включает TLS по умолчанию, так что адрес начинается с https://; http:// — только у сервера, запущенного вручную без --tls. Самоподписанный сертификат один раз спросит на странице предупреждения браузера.
• Проверьте, что адрес прослушивания не привязан к 127.0.0.1 — так он недоступен из сети (:8642 по умолчанию слушает все интерфейсы).
• Проверьте, что брандмауэр сервера пропускает 8642 (а в облаке — и группа безопасности).
• Проверьте, что планшет в той же сети или подключён к тому же VPN.

Переключился на удалённое ядро — и вижу только страницу ошибки

Страница ошибки — сама часть замысла: на неё приводят и неподнявшийся экземпляр serve, и неподключённый VPN, и опечатка в адресе — и она называет, что именно не удалось. Нажмите «Повторить» либо «Вернуться на это устройство» и посмотрите systemctl --user status agentmux на сервере. У переключения всегда есть дорога домой — застрять в удалённом режиме нельзя.

Забыт токен доступа режима serve

Токен хранится как serve-token в каталоге данных и печатается в лог при первом запуске. Чтобы сменить его, удалите этот файл и перезапустите приложение или задайте AGENTMUX_TOKEN перед запуском.

Приложение для Android не ставится или не обновляется

Сначала разрешите установку из неизвестных источников. Конфликт подписи означает, что установлена сборка с debug-подписью (её репозиторий выпускает, когда ключ подписи не настроен) — удалите старое приложение и поставьте новое. Агенты живут в удалённом tmux, их это не затронет.

Где получить помощь#

• Создайте задачу на GitHub — платформа, версия и startup-error.log (если есть) заметно ускорят разбор.
• Внутреннее устройство оркестратора (шлюз инструментов, уровни доверия, слои памяти и навыков) описано в проектном документе оркестратора.
• Блог автора: tanzhuo.xyz