Удалённый сервер — документация AIKraft Agents

AIKraft Agents можно запустить как удалённый сервер, чтобы поддерживать долгоживущие сессии на удалённой машине, подключаться к ним из нескольких клиентов (десктопное приложение, браузер или CLI) и выполнять ресурсоёмкие задачи на мощном сервере.

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

Выберите путь установки, подходящий для вашего развёртывания:

Запуск из исходного кода — установите Bun (v1.0+)
Запуск опубликованного контейнера — установите Docker

Если вы запускаете из исходного кода, установите Bun с помощью:

terminalbash

curl -fsSL https://bun.sh/install | bash

Быстрая настройка из исходного кода

Клонируйте репозиторий и запустите скрипт установки:

terminalbash

git clone https://github.com/lukilabs/craft-agents-oss.git
cd craft-agents-oss
./scripts/install-server.sh

Скрипт устанавливает зависимости, генерирует токен и выводит команду запуска. Сохраните токен — его нельзя восстановить.

Контейнер Docker

Если вам нужен просто разворачиваемый сервер, используйте публичный пакет из GitHub Container Registry:

craft-agents-server package

Используйте тег контейнера latest:

terminalbash

export CRAFT_SERVER_TOKEN=$(openssl rand -hex 32)
echo $CRAFT_SERVER_TOKEN  # Save this

docker run -d \
  --name craft-agents-server \
  --restart unless-stopped \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=$CRAFT_SERVER_TOKEN \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -v craft-agents-data:/home/craftagents/.craft-agent \
  ghcr.io/lukilabs/craft-agents-server:latest

Этот образ уже включает веб-интерфейс, доступный через браузер, поэтому вы можете открыть http://your-server:9100 сразу после запуска контейнера. Для любого сетевого развёртывания настройте TLS на обратном прокси или смонтируйте сертификаты и установите CRAFT_RPC_TLS_CERT / CRAFT_RPC_TLS_KEY.

Если вы предпочитаете Docker Compose:

terminalbash

services:
  craft-agents:
    image: ghcr.io/lukilabs/craft-agents-server:latest
    restart: unless-stopped
    ports:
      - "9100:9100"
    environment:
      CRAFT_SERVER_TOKEN: ${CRAFT_SERVER_TOKEN}
      CRAFT_RPC_HOST: 0.0.0.0
    volumes:
      - craft-agents-data:/home/craftagents/.craft-agent

volumes:
  craft-agents-data:

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

Сессии возвращают пустые ответы (без ошибок)

При запуске с --user и пользовательской директорией HOME SDK Claude Agent требует, чтобы $HOME/.claude/ была доступна для записи. Если домашняя директория доступна только для чтения (например, принадлежит root), SDK молча возвращает пустые ответы без записи ошибок в лог.

Решение: Смонтируйте доступный для записи том в путь HOME. Например, если вы запускаете как пользователь хоста с домашней директорией /Users/alice:

terminalbash

docker run -d \
  --name craft-agents-server \
  --user $(id -u):$(id -g) \
  -e HOME=/Users/alice \
  -e CRAFT_SERVER_TOKEN=$CRAFT_SERVER_TOKEN \
  -p 9100:9100 \
  -v /Users/alice/.craft-agent/docker-home:/Users/alice \
  -v /Users/alice/.craft-agent:/Users/alice/.craft-agent \
  ghcr.io/lukilabs/craft-agents-server:latest

Стек томов работает по слоям:

docker-home → /Users/alice — доступная для записи домашняя директория для SDK (~/.claude/)
.craft-agent → /Users/alice/.craft-agent — данные рабочей среды (накладываются поверх)

По умолчанию образ Docker использует HOME=/home/craftagents с предварительно созданной доступной для записи директорией. Эта проблема возникает только при переопределении HOME для соответствия пути пользователя хоста.

Веб-интерфейс не загружается

Если сервер запущен, но http://your-server:9100 возвращает 404 или ошибку подключения:

CRAFT_WEBUI_DIR не установлен — Образ Docker устанавливает это значение по умолчанию в /app/apps/webui/dist. Если ваш docker-compose.yml или файл .env переопределяет переменные окружения, убедитесь, что CRAFT_WEBUI_DIR включён или не переопределён как пустая строка.
Том затеняет директорию приложения — Монтирование тома поверх /app заменяет собой собой встроенные ресурсы веб-интерфейса. Смонтируйте тома только в /home/craftagents/.craft-agent (или вашу пользовательскую директорию HOME), а не в /app.
Старый тег образа — Образы до версии 0.8.0 не включают веб-интерфейс. Используйте latest или 0.8.0+.

Проверьте внутри контейнера:

terminalbash

docker exec craft-agents-server ls /app/apps/webui/dist/index.html
docker exec craft-agents-server echo $CRAFT_WEBUI_DIR

Ручная настройка из исходного кода

terminalbash

git clone https://github.com/lukilabs/craft-agents-oss.git
cd craft-agents-oss
bun install

Сгенерируйте токен и запустите:

terminalbash

export CRAFT_SERVER_TOKEN=$(openssl rand -hex 32)
echo $CRAFT_SERVER_TOKEN  # Save this

CRAFT_SERVER_TOKEN=$CRAFT_SERVER_TOKEN \
CRAFT_RPC_HOST=0.0.0.0 \
CRAFT_RPC_TLS_CERT=certs/cert.pem \
CRAFT_RPC_TLS_KEY=certs/key.pem \
bun run packages/server/src/index.ts

Для разработки TLS сгенерируйте самоподписанный сертификат:

terminalbash

./scripts/generate-dev-cert.sh
# Creates certs/cert.pem and certs/key.pem (valid 365 days)

Для производства используйте сертификаты от доверенного CA (например, Let's Encrypt) или разместите сервер за обратным прокси (nginx, Caddy), который завершает TLS.

Сервер выводит детали подключения при запуске:

terminalbash

CRAFT_SERVER_URL=wss://0.0.0.0:9100
CRAFT_SERVER_TOKEN=

Веб-интерфейс

Сервер может обслуживать веб-интерфейс, доступный через браузер, на том же порту.

Образ Docker: уже включает веб-интерфейс
Запуск из исходного кода: соберите и включите его с помощью:

terminalbash

# Build the web UI assets
bun run webui:build

# Start the server with Web UI enabled
CRAFT_SERVER_TOKEN=$CRAFT_SERVER_TOKEN \
CRAFT_WEBUI_DIR=apps/webui/dist \
CRAFT_RPC_HOST=0.0.0.0 \
bun run packages/server/src/index.ts

Или используйте удобный скрипт, который собирает всё:

terminalbash

bun run server:prod

Доступ к веб-интерфейку

Откройте https://your-server:9100 (или http:// без TLS) в любом браузере. Вы увидите страницу входа.

Аутентификация

Введите токен сервера в качестве пароля. При успешном входе сервер выдаёт cookie сессии.

Попытки входа ограничены по скорости — 5 за 60 секунд на IP
Сессия сохраняется до выхода или истечения срока действия cookie

Что вы можете делать

Веб-интерфейс предоставляет тот же интерфейс сессий, что и десктопное приложение — создавайте сессии, отправляйте сообщения, управляйте workspace. OAuth-потоки для Claude и Copilot работают прямо в браузере.

Никогда не запускайте без TLS в сети. Токен сервера и все данные сессий передаются по WebSocket-соединению. Без TLS любой в сети может перехвределить их.

Подключение клиентов

Десктопное приложение (гибридный режим)

Подключитесь к удалённому серверу, сохранив локальные workspace:

Нажмите на выпадающий список workspace в боковой панели
Выберите Добавить workspace... → Подключиться к удалённому серверу
Введите URL сервера (например, wss://192.168.1.100:9100) и токен
Нажмите Проверить подключение, чтобы убедиться
Выберите существующую workspace или создайте новую на сервере

После подключения удалённые workspace отображаются в переключателе workspace рядом с локальными. Значок CloudOff указывает, когда удалённая workspace недоступна.

Десктопное приложение (тонкий клиент)

Запустите приложение как чистый тонкий клиент — вся логика работает на сервере:

terminalbash

CRAFT_SERVER_URL=wss://your-server:9100 \
CRAFT_SERVER_TOKEN= \
bun run electron:start

Веб-интерфейс

Откройте URL сервера в любом браузере и войдите с помощью токена. См. Веб-интерфейс выше.

CLI-клиент

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

terminalbash

export CRAFT_SERVER_URL=wss://your-server:9100
export CRAFT_SERVER_TOKEN=

craft-cli ping
craft-cli sessions
craft-cli send abc-123 "Run the tests"

См. CLI guide для полного списка команд.

Переменные окружения

Переменная	Обязательна	По умолчанию	Описание
`CRAFT_SERVER_TOKEN`	Да	—	Токен для аутентификации
`CRAFT_SERVER_URL`	Нет	—	URL сервера для подключений клиентов
`CRAFT_RPC_HOST`	Нет	`127.0.0.1`	Адрес привязки (`0.0.0.0` для удалённого доступа)
`CRAFT_RPC_PORT`	Нет	`9100`	Порт привязки
`CRAFT_RPC_TLS_CERT`	Да*	—	Файл сертификата PEM (включает `wss://`)
`CRAFT_RPC_TLS_KEY`	Да*	—	Файл закрытого ключа PEM
`CRAFT_RPC_TLS_CA`	Нет	—	Файл цепочки CA PEM (необязательно)
`CRAFT_DEBUG`	Нет	`false`	Включить отладочное логирование

* Обязательна для удалённых подключений. Может быть опущена для разработки только на localhost.

Автоматический запуск при загрузке

Linux (systemd)

Создайте файл окружения по пути /path/to/craft-agents-oss/.env:

terminalbash

CRAFT_SERVER_TOKEN=
CRAFT_RPC_HOST=0.0.0.0
CRAFT_RPC_PORT=9100
CRAFT_RPC_TLS_CERT=/path/to/cert.pem
CRAFT_RPC_TLS_KEY=/path/to/key.pem

Создайте файл службы по пути /etc/systemd/system/craft-agents.service:

terminalbash

[Unit]
Description=AIKraft Agents Server
After=network.target

[Service]
Type=simple
User=
WorkingDirectory=/path/to/craft-agents-oss
EnvironmentFile=/path/to/craft-agents-oss/.env
ExecStart=/home//.bun/bin/bun run packages/server/src/index.ts
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Включите и запустите:

terminalbash

sudo systemctl daemon-reload
sudo systemctl enable craft-agents
sudo systemctl start craft-agents

# Check status
sudo systemctl status craft-agents

# View logs
journalctl -u craft-agents -f

macOS (launchd)

Создайте plist по пути ~/Library/LaunchAgents/com.craft.agents-server.plist:

terminalbash

<?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.craft.agents-server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOU/.bun/bin/bun</string>
    <string>run</string>
    <string>packages/server/src/index.ts</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/craft-agents-oss</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>CRAFT_SERVER_TOKEN</key>
    <string>YOUR_TOKEN</string>
    <key>CRAFT_RPC_HOST</key>
    <string>0.0.0.0</string>
    <key>CRAFT_RPC_PORT</key>
    <string>9100</string>
    <key>CRAFT_RPC_TLS_CERT</key>
    <string>/path/to/cert.pem</string>
    <key>CRAFT_RPC_TLS_KEY</key>
    <string>/path/to/key.pem</string>
  </dict>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/craft-agents.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/craft-agents.log</string>
</dict>
</plist>

Загрузите и запустите:

terminalbash

launchctl load ~/Library/LaunchAgents/com.craft.agents-server.plist

# Check status
launchctl list | grep craft

# View logs
tail -f /tmp/craft-agents.log

# Stop and unload
launchctl unload ~/Library/LaunchAgents/com.craft.agents-server.plist

Безопасный доступ

Прямое подключение к серверу из интернета не рекомендуется. Вместо этого используйте один из следующих подходов:

Tailscale (рекомендуется)

Tailscale создаёт частную сеть между вашими устройствами. Установите её на сервер и клиентские машины — не нужно настраивать проброс портов, сертификаты или правила брандмашины.

terminalbash

# On the server: bind to Tailscale IP only
CRAFT_RPC_HOST=100.x.y.z \
CRAFT_SERVER_TOKEN=$TOKEN \
bun run packages/server/src/index.ts

Трафик шифруется сквозь Tailscale, поэтому можно полностью пропустить настройку TLS-сертификатов. Сервер доступен только из вашей сети Tailscale.

Обратный прокси (nginx, Caddy)

Разместите сервер за обратным прокси, который обрабатывает завершение TLS и контроль доступа. Это стандартный подход для производственных развёртываний.

Caddy (автоматический HTTPS):

terminalbash

craft.example.com {
    reverse_proxy localhost:9100
}

nginx:

terminalbash

server {
    listen 443 ssl;
    server_name craft.example.com;

    ssl_certificate /etc/letsencrypt/live/craft.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/craft.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:9100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

При использовании обратного прокси привяжите сервер только к localhost (CRAFT_RPC_HOST=127.0.0.1) и позвольте прокси обрабатывать внешние подключения.

Cloudflare Tunnel

Cloudflare Tunnel предоставляет доступ к вашему серверу по HTTPS без открытия портов или управления сертификатами. Установите cloudflared и запустите:

terminalbash

# Quick tunnel — instant HTTPS URL, no config needed
cloudflared tunnel --url http://localhost:9100

Это выводит URL вида https://.trycloudflare.com, который можно открыть в любом браузере. Для постоянного собственного домена:

terminalbash

# One-time setup
cloudflared tunnel login
cloudflared tunnel create craft-agents
cloudflared tunnel route dns craft-agents agents.yourdomain.com

# Run the tunnel
cloudflared tunnel run --url http://localhost:9100 craft-agents

Cloudflare Tunnel автоматически обрабатывает завершение TLS — не нужно устанавливить CRAFT_RPC_TLS_CERT / CRAFT_RPC_TLS_KEY. Оставьте CRAFT_RPC_HOST=127.0.0.1, чтобы сервер прослушивал только локально.

SSH-туннель

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

terminalbash

# On the client: forward local port 9100 to the remote server
ssh -L 9100:localhost:9100 user@your-server

Затем подключитесь к ws://localhost:9100 из десктопного приложения или браузера. Туннель шифрует весь трафик по SSH.

Браузерный инструмент

Встроенный browser связывает удалённый сервер с подключённым десктопным клиентом — страницы открываются на вашей локальной машине, используя ваши cookies и авторизованные сессии. Браузерный инструмент доступен, когда подключён хотя бы один десктопный клиент; веб-интерфейс и CLI-клиенты не могут размещать окна браузера.

См. Browser on remote workspaces для модели безопасности и переключателя allowRemoteEvaluate.

Совместимость версий

Сервер включает свою версию в процесс рукопожатия при подключении. Когда клиент подключается к более старой версии сервера (до 0.8.0), отображается предупреждение о том, что некоторые функции могут быть недоступны.

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

Быстрая настройка из исходного кода

Контейнер Docker

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

Ручная настройка из исходного кода

Веб-интерфейс

Доступ к веб-интерфейку

Аутентификация

Что вы можете делать

Подключение клиентов

Десктопное приложение (гибридный режим)

Десктопное приложение (тонкий клиент)

Веб-интерфейс

CLI-клиент

Переменные окружения

Автоматический запуск при загрузке

Linux (systemd)

macOS (launchd)

Безопасный доступ

Tailscale (рекомендуется)

Обратный прокси (nginx, Caddy)

Cloudflare Tunnel

SSH-туннель

Браузерный инструмент

Совместимость версий

Нужен такой агент в вашей компании?