Skip to main content

Build & Test

Build wallet-free Locus from the repository's main branch with Xcode 26 and XcodeGen. project.yml is the source of truth for the generated Xcode project.

Build for Ollama and API accounts​

From the repository root:

brew install xcodegen
xcodegen generate
xcodebuild -project Locus.xcodeproj -scheme Locus -configuration Debug \
  -destination 'platform=macOS' -derivedDataPath build/locus \
  CODE_SIGN_IDENTITY=- DEVELOPMENT_TEAM= \
  LOCUS_DIRECT_ENTITLEMENTS=Config/LocusDirectAdHoc.entitlements \
  LOCUS_BUNDLE_CODEX=skip LOCUS_BUNDLE_CLAUDE=skip build
open build/locus/Build/Products/Debug/Locus.app

The first build downloads the standalone Python runtime. LOCUS_BUNDLE_CODEX=skip omits optional ChatGPT helpers and avoids their Rust build. LOCUS_BUNDLE_CLAUDE=skip omits the optional Claude plan runtime for this Ollama/API-only build. To include them, install Rust through rustup and remove that setting; the pinned Codex source selects its toolchain. LocusX additionally needs the signer toolchain pinned in WalletSignerCore/rust-toolchain.toml.

Use separate build directories for Locus and LocusX. Standard Locus excludes wallet code, SDKs, resources, signer helpers, and wallet browser injection. A backend setting cannot enable wallet tools in the standard staged app. The unused Mac App Store target was removed in 3.3.

Native tests​

For common native tests, replace the final build above with test -only-testing:LocusTests. LocusX uses its own scheme, build directory, and LocusXTests. Run relevant UI checks for interface changes. Consult the repository's CI workflow for the exact release checks.

Backend tests​

From the repository root, use Python 3.10 or later:

python3 -m venv agent/.venv
agent/.venv/bin/pip install -e './agent[dev]'
agent/.venv/bin/python -m pytest -q

Tests use disposable application data. CI currently uses Python 3.14.

Mobile checks​

From the mobile checkout with its pinned Flutter SDK:

flutter pub get
flutter analyze
flutter test
flutter build apk --debug
flutter build ios --simulator --no-codesign

Packaging​

Packaged apps must include the agent runtime. LOCUS_BUNDLE_MODE=skip is a compile-only shortcut, not a deliverable app. Direct release builds normally deliver ChatGPT and Claude helpers as separate verified components; Debug builds bundle their enabled helpers. Component delivery verifies checksums and signing identity before execution.

Locus 2.7.0 introduced automatic updates on a separate signed appcast-locus.xml feed. Package from a clean revision with the release signing identity, the full agent runtime, notarization, and the edition audit. Publish the app ZIP, new feed, unchanged legacy appcast.xml, components.json, and all referenced component archives together. Never publish wallet-free Locus through the preserved legacy feed. See the repository's Contributing guide and Editions guide for current source build and packaging details, which may advance beyond these release docs.

Portable runtime candidates​

The 3.0 source includes complete portable runtime packaging for linux-x86_64, linux-arm64, and macos-arm64. Build on the target OS and architecture from a clean committed checkout:

python3 Tools/PrepareRemoteRuntime.py \
  --target macos-arm64 --require-clean \
  --output build/runtime-packages/locus-runtime-macos-arm64.tar.gz

The builder produces the archive, its .sha256, and a .build.json provenance report. Pinned Python and helper downloads are hash-checked on download and cache reuse. Dependencies use the hashed runtime lockfile; the archive includes source revision, a file manifest, and license notices. Deterministic archive metadata makes packaging the same prepared layout reproducible, without claiming all dependency builds are identical.

The standard builder includes the pinned ChatGPT helper. The lower-level Tools/PackageRemoteRuntime.py accepts an optional --claude-helper; only packages containing that verified binary advertise Claude plan. Setup requires Python 3.10+, while execution uses bundled Python. Linux needs glibc 2.28+ and systemd user support; macOS needs 14+, Apple Silicon, and an active graphical login.

An isolated package check can exercise service installation and failed-update rollback:

python3 Tools/SmokeRemoteRuntime.py \
  --package build/runtime-packages/locus-runtime-macos-arm64.tar.gz \
  --sha256 REVIEWED_PACKAGE_SHA256 \
  --service-manager --exercise-rollback \
  --output build/runtime-packages/macos-arm64.smoke.json

Use the checksum from the reviewed candidate. The smoke runner uses a disposable namespace, deterministic provider fixture, and separate signed-out helper accounts. It verifies service restart, controller disconnect, a scheduled verified result, usage, a reviewed reusable check, and rollback without using production credentials. The Runtime package candidates workflow retains evidence and passing target archives; it does not publish a production release.

Release gates remain separate: signed desktop background-service registration, live SSH installation and host-key change rejection, login/reboot lifecycle, real connectors, and bounded provider sign-in, calls, expiry, and recovery. Fixture-based checks do not establish these live behaviors. See the source runtime readiness report for current packaging and recovery details.

The Claude plan source guide records its pinned SDK/runtime, direct component versus bundled distribution, optional remote packaging, and outstanding preview authentication and distribution-approval gates. Task recovery and comparative provider campaigns also retain their explicit validation limits.