Paseo объединяет консольные кодинг-агенты в единую систему с локальным управляющим демоном, автоматической изоляцией задач в Git worktrees, проксированием портов и нативным управлением со смартфона, десктопа или веб-интерфейса.
Что это
Paseo — это открытая селф-хостед платформа оркестрации и панель управления (control plane) для автономных кодинг-агентов. Она рассчитана на консольные инструменты, которые разработчики уже используют локально: Claude Code, OpenAI Codex, GitHub Copilot CLI, OpenCode, Pi, агентов на базе протокола ACP (Agent Client Protocol) и кастомных провайдеров моделей.
Большинство кодинг-агентов создаются как утилиты для одного терминального сеанса. Пока разработчик сидит за рабочим компьютером и решает одну задачу, такого режима хватает. Трудности начинаются при попытке масштабировать процесс: запуск двух или трёх агентов в одной рабочей директории приводит к тому, что модели одновременно правят одинаковые файлы, сбивают контекст и ломают чужие тесты. Вторая проблема — автономность: если агент выполняет крупный рефакторинг на 40 минут, разработчик привязан к экрану, поскольку следить за терминалом и подтверждать команды с телефона через мобильный SSH неудобно.
Paseo решает эти задачи разделением на локальный управляющий демон и клиентские интерфейсы. Демон развёртывается прямо на вашей рабочей машине, домашнем сервере или удалённом dev-сервере. Он имеет полный доступ к локальному окружению, установленным компиляторам, базам данных и веткам Git. А подключаться к нему можно через нативные приложения для macOS, Windows, Linux, мобильный клиент для iOS и Android или встроенный веб-интерфейс.
Ключевое правило: Paseo не предоставляет собственные нейросети и не выступает облачным посредником для кода. Это координационный слой, который запускает ваши локальные CLI-агенты на вашем оборудовании, изолирует их рабочие среды и открывает к ним защищённый доступ с любого устройства.
Зачем нужно
- Связь с агентом со смартфона без белого IP и проброса портов — мобильное приложение подключается к домашнему или офисному компьютеру через защищённое реле со сквозным шифрованием (E2EE relay) по одноразовому QR-коду либо напрямую по локальной сети и VPN (Tailscale).
- Параллельная работа нескольких моделей над одним проектом — платформа автоматически создаёт под каждую задачу отдельный Git worktree и выделяет виртуальный поддомен с уникальным портом (
web.<ветка>.<проект>.localhost), предотвращая конфликты при одновременном запуске dev-серверов. - Оркестрация через встроенные инструменты Paseo Tools — запущенные агенты получают программный доступ к платформе: они могут сами открывать изолированные воркспейсы, делегировать подзадачи другим моделям, запускать фоновые терминалы и проверять результаты тестов.
- Прямое использование собственных аккаунтов (BYOK) — запросы к языковым моделям отправляются напрямую с вашей машины по вашим API-ключам или подпискам (Anthropic Claude, OpenAI, GitHub Copilot). Исходный код проекта не передаётся сторонним облачным сервисам.
- Интеграция с GitHub и pull request — встроенная связка с GitHub CLI (
gh) позволяет агентам подтягивать контекст обсуждения, запускать проверки CI, работать с форками и автоматически готовить ветки к ревью. - Автоматизация по расписанию и внешним вебхукам — сервис Paseo Hub запускает агентов по расписанию (Schedules) или внешним триггерам: при назначении issue, упоминании разработчика в PR на GitHub, сообщениях в Slack или Discord.
- Локальный голосовой ввод и озвучивание — модули распознавания речи (STT) и синтеза голоса (TTS) работают на мощностях устройства без передачи аудиозаписей во внешние облака.
Как устроено
| Компонент | Назначение | Особенности реализации |
|---|---|---|
| Paseo Daemon | Ядро управления процессами | Фоновый процесс на рабочей машине, исполняет команды CLI-агентов, держит локальное состояние в ~/.paseo |
| Клиенты (Desktop, Mobile, Web) | Рабочие интерфейсы | Нативные сборки для десктопа, мобильное приложение на React Native (не webview) и встроенный веб-сервер на порту 6767 |
| E2EE Relay | Канал удалённого взаимодействия | Туннель со сквозным шифрованием для безопасного подключения клиентов через интернет без настройки NAT |
| Worktree & Port Manager | Изоляция рабочих сред | Создаёт независимые рабочие деревья Git под каждую задачу и динамически маршрутизирует порты тестовых серверов |
| Paseo Tools & SDK | Слой агентской оркестрации | Системный инструментарий для создания суб-воркспейсов, управления терминалами и сборки кастомных плагинов на TypeScript |
| Paseo Hub | Диспетчер внешних событий | Селф-хостед сервер для триггеров: принимает вебхуки из GitHub, Slack, Discord и поднимает под них задачи агентам |
| Провайдеры (Providers) | Адаптеры инструментов | Поддержка Claude Code, Codex, Copilot, OpenCode, Pi, протокола ACP и кастомных моделей с раздельной настройкой прав |
Механика работы с кодом и изоляция
Когда вы ставите агенту задачу, Paseo не затрагивает текущее состояние файлов в вашем редакторе. Демон выполняет команду git worktree add, создавая независимую копию рабочей директории в служебном каталоге. Для этой копии выделяется виртуальный хост, например web.fix-auth.my-app.localhost. Если проект требует запуска локального веб-сервера на порту 3000, встроенный реверс-прокси перенаправляет запросы так, чтобы три одновременно запущенных сервера разных агентов не конфликтовали за порт.
В интерфейсе приложения рабочий процесс разбит на сплит-панели: рядом с окном диалога отображаются терминал агента, древовидный diff изменённых файлов с контекстным меню и встроенный браузер для визуального контроля правок. Клиенты получают обновления по WebSocket-протоколу. Если интернет-соединение на смартфоне пропало, агент на компьютере продолжит выполнять тесты и писать код, а при повторном открытии приложения интерфейс мгновенно восстановит актуальное состояние.
Расширяемость и плагины (v0.8)
Начиная с версии 0.8 платформа использует модульную систему плагинов с явным разделением на клиентскую и серверную части. Плагины позволяют добавлять собственные кнопки в шапку интерфейса, интерактивные элементы в поле ввода промптов (composer pills), кастомные модальные окна и новые типы провайдеров. Для каждого провайдера можно независимо определить список разрешённых инструментов, кастомные иконки и правила подтверждения системных команд.
Когда использовать
| Ситуация | Подходит / не подходит | Почему |
|---|---|---|
| Параллельная разработка нескольких фич | Подходит | Агенты изолированы в независимых Git worktrees и не мешают друг другу перезаписью файлов и конфликтами портов |
| Контроль длительных задач вне рабочего места | Подходит | Нативное мобильное приложение позволяет читать рассуждения модели, отвечать на запросы и подтверждать diff с телефона |
| Фоновые ночные задачи и автоматическое ревью | Подходит | Встроенный планировщик по крону и связка с GitHub CLI берут на себя рутинную проверку зависимостей и разбор PR |
| Координация цепочек из нескольких агентов | Подходит | Через Paseo Tools агент-архитектор может порождать суб-агентов на других моделях и контролировать их выполнение |
| Поиск облачной песочницы без локального окружения | Не подходит | Paseo не предоставляет виртуальные серверы в облаке; всё рабочее окружение и компиляторы должны быть на вашем хосте |
| Эпизодический запуск одной команды на 5 минут | Не подходит | Для редкого запуска одного сеанса Claude Code развёртывание демона создаёт избыточный уровень инфраструктуры |
Пример
Вариант 1. Запуск через официальный CLI на рабочей машине
Установка глобального пакета и запуск демона:
# Установка CLI-клиента и демона
npm install -g @getpaseo/cli
# Запуск демона
paseoПри первом запуске утилита спросит, требуется ли включить сквозное шифрование (E2EE relay), после чего сгенерирует QR-код прямо в терминале. Отсканировав этот код в мобильном приложении Paseo на телефоне, вы мгновенно связываете устройства.
Если требуется запустить команду на удалённом хосте через CLI:
paseo --host 192.168.1.50:6767 workspace listВариант 2. Развёртывание на сервере через Docker Compose
Для выделенных серверов разработки или домашних лабораторий (NAS) удобно использовать контейнер со встроенным веб-интерфейсом:
services:
paseo:
image: ghcr.io/getpaseo/paseo:latest
containername: paseo
restart: unless-stopped
ports:
- "6767:6767"
environment:
- PASEOPASSWORD=вашнадежныйпарольдоступа
- ANTHROPICAPIKEY=${ANTHROPICAPIKEY}
- OPENAIAPIKEY=${OPENAIAPI_KEY}
volumes:
- ~/.paseo:/home/paseo
- /var/run/docker.sock:/var/run/docker.sock
- ~/projects:/workspaceВеб-интерфейс управления будет доступен в браузере по адресу http://localhost:6767.
Ограничения
Ограничения
Что учитывать
Перед установкой и настройкой платформы важно знать системные требования и технические границы.
Предварительная установка CLI-агентов
— Paseo не содержит внутри готовых моделей или встроенных бинарников агентов; Claude Code, Codex, Copilot или OpenCode должны быть установлены, авторизованы и проверены в терминале хоста до запуска демона.
Требования к версиям операционных систем
— десктопное приложение для macOS поддерживает только macOS 13 (Ventura) и новее; на дистрибутивах Linux (Ubuntu 24.04+, Fedora) для запуска песочницы Chromium в AppImage может потребоваться пакет libfuse2t64 либо установка официальных пакетов .deb или .rpm.
Высокие требования к оперативной памяти и диску
— каждый запущенный агент в изолированном Git worktree создаёт собственные фоновые процессы, кэши и копии зависимостей; параллельный запуск 4–5 задач на тяжелых репозиториях быстро расходует оперативную память и свободный объем SSD.
Ограничения базового Docker-образа
— официальный Docker-контейнер содержит только демон Paseo и веб-интерфейс; компиляторы, языковые среды (Node.js, Python, Go, Rust) и необходимые CLI-агенты под конкретные проекты нужно подключать в образ самостоятельно через кастомный Dockerfile.
Зависимость от утилиты GitHub CLI
— функционал автоматической работы с pull request, форками и ветками требует предварительной авторизации локальной утилиты gh на хосте.
Антипаттерны
Антипаттерны
Чего не делать
Ошибки в настройке прав и параллелизма снижают стабильность разработки и создают угрозу для безопасности рабочей машины.
Запускать агентов в одной рабочей директории без worktrees
— отключение изоляции веток при одновременной работе нескольких моделей неизбежно приводит к перезаписи файлов, конфликтам слияния и порче локального кода.
Включать полный автоапрув опасных команд для внешних задач
— автоматическое одобрение прав (permissions) при обработке чужих репозиториев или непроверенных pull request создаёт риск выполнения вредоносного скрипта прямо на вашем хосте.
Хранить токены и секреты в кодовой базе воркспейса
— запись API-ключей в файлы репозитория вместо системных переменных окружения хоста грозит случайной утечкой доступов при публикации веток агентом в публичный репозиторий.
Оставлять завершённые воркспейсы без архивации
— брошенные рабочие деревья Git и временные файлы сборки накапливаются в служебных каталогах и постепенно забивают диск рабочей машины.
Использовать E2EE-реле без пароля на демоне
— публикация управляющего порта или подключение внешних клиентов без установленного PASEO\_PASSWORD открывает доступ к выполнению команд на вашем компьютере любому, кто перехватит сопряжение.
Чеклист
Чеклист
Проверка перед запуском
Пошаговый план подготовки хоста и первой настройки Paseo.
Консольные агенты работают локально
— в терминале хоста проверен успешный вызов команд claude, codex или других используемых утилит, подтверждено наличие авторизации и доступ к API.
Утилита GitHub CLI аутентифицирована
— команда gh auth status подтверждает успешный вход, чтобы платформа могла автоматически связывать воркспейсы с ветками и pull request.
Пароль доступа задан
— переменная PASEO\_PASSWORD указана в конфигурации демона для защиты локального веб-интерфейса и сетевого порта.
Сопряжение с мобильным клиентом проверено
— приложение на смартфоне успешно подключилось к компьютеру через сканирование QR-кода по шифрованному E2EE-реле или через защищённый VPN.
Тестовый воркспейс запущен
— проект открыт в панели, проверено автоматическое создание Git worktree, отображение diff в реальном времени и изоляция выделенного порта тестового сервера.
Настроены правила подтверждения команд
— в настройках провайдера проверено, что деструктивные системные действия требуют ручного подтверждения пользователя.
Ссылки
Ссылки
- Документация: Paseo Documentation
- Официальный сайт: Paseo
- Репозиторий: getpaseo/paseo