Запуск Quarshell на macOS¶

В этой инструкции CLI и Gateway работают на Mac, а sandbox запускается в Docker-контейнере внутри Docker Desktop. API Quarshell пока нестабильны и остаются в серии 0.x.

Требования¶

macOS на Intel (x86_64) или Apple silicon (arm64); установщик выберет подходящий архив.
Установленный и запущенный Docker Desktop. Инструкция — в официальной документации.
curl, sh и shell с ~/.local/bin в PATH.

Docker Desktop запускает container engine в Linux VM. CLI и Gateway Quarshell работают на macOS, сам sandbox — в этой VM. Передайте проект через --upload.

1. Установите CLI и Gateway¶

curl -fsSL https://raw.githubusercontent.com/KLORQ/quarshell-cli/main/install.sh | CAUTEM_NO_START=1 sh

Установщик проверяет SHA-256 checksum и ставит cautem, quarshell-gateway и helper-файлы в ~/.local/bin. CAUTEM_NO_START=1 позволяет сначала запустить engine, а затем выбрать backend при запуске Gateway.

Если установщик сообщил, что ~/.local/bin отсутствует в PATH, добавьте в ~/.zshrc:

printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.zshrc
source ~/.zshrc

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

cautem version

2. Запустите Docker Desktop¶

Откройте Docker Desktop и дождитесь состояния запущенного engine. В Terminal проверьте подключение:

docker version
docker info
cautem doctor
cautem gateway ensure
cautem status

Команда docker должна работать без sudo. Оставляйте Docker Desktop запущенным во время работы с Quarshell.

3. Скачайте sandbox image¶

docker pull ghcr.io/cautem/cautem/sandboxes/base:latest
export CAUTEM_USE_GHCR=1

Переменная переключает alias base на опубликованный image. Для новых окон Terminal добавьте export CAUTEM_USE_GHCR=1 в ~/.zshrc.

4. Создайте и запустите sandbox¶

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

mkdir -p ~/.config/cautem
cat > ~/.config/cautem/default-policy.yaml <<'EOF'
version: 1
filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /app
    - /etc
    - /var/log
    - /AGENTS.md
  read_write:
    - /tmp
    - /dev/null
    - /sandbox
    - /workspace
landlock:
  compatibility: best_effort
network_policies: {}
EOF

Создайте sandbox, загрузите в него текущую папку и выполните команду внутри:

cautem sandbox create \
  --name demo \
  --gateway-workspace default \
  --from base \
  --policy ~/.config/cautem/default-policy.yaml \
  --upload "$PWD"

cautem sandbox list
cautem sandbox exec demo -- uname -a
cautem sandbox connect demo

connect открывает shell; выход — exit. --upload отправляет копию файлов во время создания sandbox, это не live mount каталога с Mac. Политика пока не разрешает сетевые адреса. Добавьте точечные разрешения перед запуском агента, которому нужен интернет: сетевая политика.

Удалите sandbox после работы:

cautem sandbox delete demo

Альтернатива: Podman¶

Установите Podman по официальной инструкции, создайте и запустите Linux VM:

podman machine init
podman machine start
podman info

Выберите Podman до первого запуска локального Gateway: именно Gateway владеет compute backend.

export CAUTEM_GATEWAY_RUNTIME=podman
cautem gateway ensure

Скачайте image командой podman pull ghcr.io/cautem/cautem/sandboxes/base:latest; оставьте CAUTEM_USE_GHCR=1 включённым.

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

Gateway недоступен: выполните cautem gateway ensure, затем проверьте лог ~/Library/Application Support/cautem/gateway.log.
Не работает docker info: запустите Docker Desktop и проверьте выбранный context командой docker context ls.
Не скачивается image: проверьте доступ к registry через docker pull.
cautem doctor не находит Docker: проверьте docker в том же Terminal.