Installation

Build and install Loom using Nix or Cargo with detailed setup instructions

Build Methods

Loom supports two build methods:

1. Nix with cargo2nix (Preferred) - Reproducible builds with per-crate caching
2. Cargo (Development) - Standard Rust toolchain builds

Nix builds are significantly faster on incremental changes due to per-crate caching. Use Cargo for quick iteration during development.

Nix Build (Preferred)

Prerequisites

1. Install Nix

   Install Nix with flakes enabled:

   curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
   
2. Enable Flakes

   Flakes should be enabled by default with the Determinate Systems installer. Verify:

   nix --version
   

Building Loom

Loom uses cargo2nix for reproducible builds with per-crate caching:

CLI

# Build the CLI
nix build .#loom-cli-c2n

# Binary available at:
./result/bin/loom --version

# Build the server
nix build .#loom-server-c2n

# Binary available at:
./result/bin/loom-server

# Build any crate in the workspace
nix build .#loom-common-core-c2n
nix build .#loom-common-thread-c2n
nix build .#loom-server-auth-c2n

# Build container images
nix build .#loom-server-image
nix build .#weaver-image

cargo2nix Workflow

When you modify Cargo.toml or Cargo.lock:

1. Update Cargo.lock

   cargo update
   
2. Regenerate Cargo.nix

   cargo2nix-update
   

   This regenerates Cargo.nix with the updated dependency graph.

3. Commit Both Files

   git add Cargo.lock Cargo.nix
   git commit -m "Update dependencies"
   

cargo2nix doesn’t track include_str! file changes. If you add/modify migration files or other embedded resources, run cargo2nix-update to force a rebuild by changing the hash.

Cargo Build (Development)

Prerequisites

1. Install Rust

   Install Rust using rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
2. Verify Installation

   rustc --version
   cargo --version
   

Building with Cargo

Workspace

# Build everything in the workspace
cargo build --workspace

# Release build
cargo build --workspace --release

# Build just the CLI
cargo build --release -p loom-cli

# Build the server
cargo build --release -p loom-server

# Run all tests
cargo test --workspace

# Test a specific crate
cargo test -p loom-common-core

# Test a specific function
cargo test -p loom-common-core test_agent

# Run clippy (linter)
cargo clippy --workspace -- -D warnings

# Format code
cargo fmt --all

# Check formatting without changing files
cargo fmt --all -- --check

Full Check

Run all quality checks:

make check

This runs:

1. cargo fmt --all -- --check - Format verification
2. cargo clippy --workspace -- -D warnings - Linting
3. cargo build --workspace - Build
4. cargo test --workspace - Tests

Build Profiles

Loom uses optimized build profiles:

Development Profile

Cargo.toml

[profile.dev]
debug = 1                    # Reduced debug info
split-debuginfo = "unpacked" # Faster linking
incremental = true           # Enable incremental compilation

Fast Profile

For git hooks and quick iteration:

cargo build --profile dev-fast

Cargo.toml

[profile.dev-fast]
inherits = "dev"
debug = 0                    # No debug info
codegen-units = 512          # Maximum parallelism

Release Profile

Cargo.toml

[profile.release]
lto = false                  # No link-time optimization
opt-level = 0                # No optimization for fastest compile
codegen-units = 256          # High parallelism
strip = "debuginfo"          # Strip debug symbols

Loom’s release profile prioritizes fast compilation over runtime performance since deployment uses Nix builds.

Installation Locations

System-wide Installation

Nix

Add to your ~/.config/nixpkgs/config.nix or NixOS configuration:

{
  environment.systemPackages = [
    (import /path/to/loom).packages.x86_64-linux.loom-cli-c2n
  ];
}

Cargo

cargo install --path crates/loom-cli

This installs to ~/.cargo/bin/loom

Development Installation

For development, use the binary directly:

# Cargo build
./target/release/loom --version

# Nix build
./result/bin/loom --version

Web Frontend

The web UI is built with SvelteKit:

1. Install pnpm

   curl -fsSL https://get.pnpm.io/install.sh | sh -
   
2. Install Dependencies

   cd web/loom-web
   pnpm install
   
3. Run Development Server

   pnpm dev
   

   Open http://localhost:5173

4. Build for Production

   pnpm build
   

Server Deployment

Loom server runs on NixOS with auto-update:

NixOS Auto-Update

Deployments happen automatically on git push to trunk:

git push origin trunk

The production server:

1. Checks for new commits every 10 seconds
2. Rebuilds using Nix when changes detected
3. Restarts the loom-server systemd service

Verify Deployment

1. Check Deployed Revision

   sudo cat /var/lib/nixos-auto-update/deployed-revision
   
2. Check Service Status

   sudo systemctl status nixos-auto-update.service
   sudo systemctl status loom-server
   
3. View Update Logs

   sudo journalctl -u nixos-auto-update.service -f
   
4. Verify Health Endpoint

   curl -s https://loom.ghuntley.com/health | jq .
   

Force Rebuild

If auto-update is stuck:

sudo rm /var/lib/nixos-auto-update/deployed-revision
sudo systemctl start nixos-auto-update.service

Database Migrations

All migrations live in crates/loom-server/migrations/:

Adding Migrations

1. Create Migration File

   # Find next available number
   ls crates/loom-server/migrations/
   
   # Create new migration (e.g., 025_new_feature.sql)
   touch crates/loom-server/migrations/025_new_feature.sql
   
2. Write SQL

   crates/loom-server/migrations/025_new_feature.sql

   -- Add your migration SQL
   CREATE TABLE IF NOT EXISTS new_table (
     id TEXT PRIMARY KEY,
     created_at INTEGER NOT NULL
   );
   
3. Force Rebuild

   Critical: cargo2nix doesn’t track include_str! changes. You must regenerate Cargo.nix:

   cargo2nix-update
   git add Cargo.nix crates/loom-server/migrations/025_new_feature.sql
   git commit -m "Add new feature migration"
   

   Without this, the deployed binary won’t include the new migration!

Migration Testing

Test migrations locally:

LOOM_SERVER_DB_PATH=/tmp/test.db ./target/release/loom-server

Migrations run automatically on server startup.

Troubleshooting

Nix Build Fails

# Clear nix cache
nix-collect-garbage

# Rebuild
nix build .#loom-cli-c2n --rebuild

Cargo Build Fails

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Rebuild
cargo build --workspace

cargo2nix Out of Sync

If Nix build fails with dependency errors:

# Ensure Cargo.lock is up to date
cargo update

# Regenerate Cargo.nix
cargo2nix-update

# Try build again
nix build .#loom-cli-c2n

Next Steps

Quick Start

Start your first REPL session

Configuration

Configure Loom for your environment

Development Guide

Learn about code style, testing, and contributing

Deployment

Deploy Loom server to production