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

AstraCode распространяется как: - готовые licensed- и nolicense-архивы в GitLab Package Registry проекта astracode/astra-code-build (Linux x86_64-gnu и macOS Apple Silicon); - upstream-артефакты CI, предназначенные для сборочного конвейера; - исходный код, который разработчик может собрать через 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

Для доступа к внутреннему GitLab требуется корпоративная сеть или VPN. Архив также можно получить напрямую от команды AstraCode. Имена ниже используют шаблон версии X.Y.Z.

Архивы бывают двух типов:

• licensed — перед запуском требуется активация лицензии;
• nolicense — проверка лицензии отключена.

Внутреннее устройство gate и различия release channels описаны в 24-license.

Linux x86_64

Licensed-сборка:

tar -xzf astracode-linux-x86_64-gnu-X.Y.Z.tar.gz
cd astracode-linux-x86_64-gnu-X.Y.Z
./bin/astracode license activate --file /path/to/license.key
./bin/astracode -C /path/to/project

Nolicense-сборка:

tar -xzf astracode-linux-x86_64-gnu-nolicense-X.Y.Z.tar.gz
cd astracode-linux-x86_64-gnu-nolicense-X.Y.Z
./bin/astracode -C /path/to/project

macOS Apple Silicon

Licensed-сборка:

mkdir -p "$HOME/astracode-X.Y.Z"
unzip astracode-macos-X.Y.Z.zip -d "$HOME/astracode-X.Y.Z"
cd "$HOME/astracode-X.Y.Z"
xattr -dr com.apple.quarantine ./astracode
./astracode license activate --file /path/to/license.key
./astracode -C /path/to/project

Nolicense-архив называется astracode-macos-nolicense-X.Y.Z.zip; активация для него не требуется.

Опционально: добавить astracode в PATH

Храните распакованную директорию в постоянном месте, затем создайте ссылку:

mkdir -p "$HOME/.local/bin"
# Linux: выполнить из корня распакованного архива
ln -sfn "$(pwd)/bin/astracode" "$HOME/.local/bin/astracode"

# macOS: выполнить из директории с бинарником
ln -sfn "$(pwd)/astracode" "$HOME/.local/bin/astracode"

Если ~/.local/bin отсутствует в PATH, добавьте его в конфигурацию shell. При обновлении распакуйте новую версию в отдельную директорию, проверьте её и перенаправьте ссылку на новый бинарник.

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

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-сборки зависит от установленного target и системного linker/toolchain.

Bazel

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

bazel build //astracode-rs/cli:astracode

MODULE.bazel лежит в корне репозитория, BUILD.bazel — в крейтах. Текущий GitLab release pipeline собирает бинарники через Cargo; наличие Bazel-цели не означает побитовой воспроизводимости релизных артефактов.

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

astracode

При первом запуске: 1. Создаётся директория ~/.astracode/. 2. Генерируется installation_id. 3. Открывается мастер настройки провайдера (можно пропустить и сделать через /model потом). 4. Итоговый sandbox и approval policy выбираются из конфигурации, профиля разрешений, платформы и trust-статуса проекта; фактические значения показывает /status.

Для headless-режима:

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

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

Получите новый архив тем же способом, распакуйте его в отдельную директорию и проверьте запуск. Если использовалась ссылка ~/.local/bin/astracode, переключите её на новый бинарник. Конфигурация и пользовательские данные находятся отдельно в $ASTRACODE_HOME и при замене бинарника сохраняются.

После обновления секреты в ~/.astracode/secrets/local.age обычно остаются работоспособны: зашифрованный файл и ключ не привязаны к версии бинарника. Ключ может храниться в secrets/local.key или в OS keyring — в зависимости от платформы и ASTRACODE_PROVIDER_SECRETS_KEY_STORAGE. См. 09-security.md.

6. Удаление

rm "$HOME/.local/bin/astracode"  # только созданная ранее ссылка

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

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

astracode --version
astracode debug models       # проверка каталога моделей (см. /debug-config в TUI для слоёв конфига)
astracode mcp list           # список зарегистрированных MCP

В TUI можно выполнить /status — покажет текущую модель, провайдера, sandbox, локаль.

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

9. Troubleshooting

bwrap: setting up uid map: Permission denied — Linux отключил unprivileged user namespaces. Решение: sudo sysctl kernel.unprivileged_userns_clone=1. Параметр [features].use_legacy_landlock = true в config.toml устарел (deprecation notice) и не рекомендуется — используйте sysctl или обновлённый sandbox.

Failed to decrypt secrets file — текущий file/keyring key не подходит к vault. Не удаляйте единственную копию: остановите AstraCode, сохраните secrets/local.age и secrets/local.key (если он есть), затем следуйте процедуре восстановления.

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

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

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