02. Установка и сборка

AstraCode распространяется как: - бинарные сборки в GitLab Package Registry (Linux x86_64-gnu, macOS arm64); - npm-пакет @astracode/astracode-cli (тонкая обёртка, выбирающая бинарник по платформе); - из исходников через cargo или bazel.

1. Системные требования

Дополнительно для Linux: - bwrap (bubblewrap) — рекомендуется (для песочницы). Без него используется встроенный vendored bwrap. - git — для большинства возможностей. - Сетевой доступ к выбранному провайдеру моделей.

2. Установка готовых бандлов

Бандлы лежат в Package Registry проекта astracode/astra-code-build (project ID 286):

https://gitlab.prosto.aib.pro/astracode/astra-code-build/-/packages

Linux:

curl -k -L -o astracode.tar.gz \
  "https://gitlab.prosto.aib.pro/api/v4/projects/286/packages/generic/astracode-linux-x86_64-gnu/0.4.11/astracode-linux-x86_64-gnu-0.4.11.tar.gz"
tar xzf astracode.tar.gz
sudo mv astracode /usr/local/bin/
astracode --version

macOS (arm64):

curl -L -o astracode.zip \
  "https://gitlab.prosto.aib.pro/api/v4/projects/286/packages/generic/astracode-macos/0.4.11/astracode-macos-0.4.11.zip"
unzip astracode.zip
mv astracode /usr/local/bin/
astracode --version

Флаг -k для Linux нужен потому, что у GitLab self-signed сертификат.

3. Установка через npm

npm install -g @astracode/astracode-cli@0.4.11
astracode --version

npm-пакет содержит JS-обёртку, которая при запуске выбирает бинарник для текущей платформы из установленных platform-specific пакетов (@astracode/astracode-cli-<platform>).

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

Cargo

git clone <repo-url> astracode
cd astracode/astracode-rs
cargo build --release --bin astracode

Бинарник окажется в target/release/astracode.

Зависимости (Linux): - Rust toolchain (стабильная версия из rust-toolchain.toml). - pkg-config, libssl-dev, libsqlite3-dev, cmake, clang.

Зависимости (macOS): - Xcode Command Line Tools. - Rust toolchain.

Cross-compile для Linux x86_64-gnu

cargo build --release --target x86_64-unknown-linux-gnu --bin astracode

Для cross-сборки macOS arm64 → x86_64 или наоборот используется обычный Rust toolchain target.

Bazel

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

bazel build //astracode-rs/cli:astracode

MODULE.bazel лежит в корне репо, BUILD.bazel — в каждом крейте. Используется в CI для гарантии бит-в-бит воспроизводимости.

5. Первый запуск

astracode

При первом запуске: 1. Создаётся директория ~/.astracode/. 2. Генерируется installation_id. 3. Открывается мастер настройки провайдера (можно пропустить и сделать через /model потом). 4. Режим sandbox по умолчанию зависит от доверия к проекту: для нового (недоверенного) каталога без явного sandbox_mode — read-only; после принятия решения о доверии (trusted/untrusted) — workspace-write (на Windows без включённого экспериментального sandbox — всё равно read-only).

Для режима без графического интерфейса:

astracode exec "Fix the failing test in tests/auth.rs"

6. Обновление

Через astracode update (стандартный путь для standalone-инсталла):

astracode update

Идёт через cli/src/main.rs::run_update_command → astracode_tui::self_update::perform_self_update. Resolve версии через gitlab_registry::fetch_latest_release, download tar.gz/zip с проверкой SHA-256, atomic symlink swap ~/.astracode/packages/standalone/current → releases/0.4.11-<target>/. Прогресс печатается между шагами (resolving, downloading, installed). CLI-путь не делает Command::exec нового бинаря (только TUI /update делает — чтобы вернуть пользователя в TUI без рестарта shell).

Subcommand::Update exempt от license-gate (cli/src/main.rs::license_exempt) — обновляться можно даже без активной лицензии, чтобы можно было откатиться/обновиться до версии где ключ известно работает.

TUI /update: в interactive-сессии можно нажать /update — астракод предложит modal с описанием новой версии, после установки делает CommandExt::exec() нового бинаря с теми же argv, пользователь оказывается в TUI новой версии.

Через npm:

npm update -g @astracode/astracode-cli

Бинарник вручную: Скачать новую версию из Package Registry и перезаписать /usr/local/bin/astracode.

После обновления секреты в ~/.astracode/secrets/local.age остаются работоспособны — keyring service="astracode" и account = SHA256(canonical($ASTRACODE_HOME)) версия-независимы. Если decrypt не работает после обновления — это значит, что keyring потерял пароль, не проблема версии (см. 09-security.md).

7. Удаление

rm /usr/local/bin/astracode      # бинарник
npm uninstall -g @astracode/astracode-cli   # npm-пакет
rm -rf ~/.astracode              # ВСЯ конфигурация, сессии, секреты (БЕЗВОЗВРАТНО!)

Перед удалением ~/.astracode экспортируйте секреты через /skills → secrets-export (если такой скилл установлен), или сохраните API-ключи отдельно.

8. Проверка установки

astracode --version
astracode mcp list           # список зарегистрированных MCP

В TUI можно выполнить /status — покажет текущую модель, провайдера, sandbox, локаль; а /debug-config — слои конфига с источниками значений.

9. Переменные окружения для установки

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

bwrap: setting up uid map: Permission denied — Linux отключил unprivileged user namespaces. Решение: sudo sysctl kernel.unprivileged_userns_clone=1, либо включить функцию [features].use_legacy_landlock = true в конфиге.

Failed to decrypt secrets file — keyring разъехался с файлом. Лечение: rm ~/.astracode/secrets/local.age, заново ввести API-ключи через /model.

Could not find suitable model provider — провайдер не настроен. Запустите /model или отредактируйте [[providers]] в config.toml.

TUI «висит» на старте — скорее всего, MCP-сервер с required = true не отвечает. Проверьте логи в ~/.astracode/log/astracode-tui.log.

См. также 03-configuration.md для тонкой настройки.