Skip to main content

macOS Installation

Lattice works on macOS 13+ (Intel and Apple Silicon).

Quick Install

bash
curl -fsSL https://uselovelace.com/lattice/install.sh | sh

This script:

  • Downloads the appropriate binary (Intel or Apple Silicon)
  • Installs to /usr/local/bin/lattice-ctl
  • Sets up launchd service for auto-start
  • Creates ~/.lovelace/lattice/ configuration directory

Step-by-Step Installation

Step 1: Download and Install

bash
# Run the installation script
curl -fsSL https://uselovelace.com/lattice/install.sh | sh

# Verify it installed
which lattice-ctl
# Output: /usr/local/bin/lattice-ctl

Step 2: Start the Service

bash
# Start the daemon
lattice-ctl daemon start

# Verify it's running
lattice-ctl ping

Expected output:

✓ Lattice daemon is running (PID: 12345)
  Uptime: 2 seconds
  Socket: /var/folders/[...]/lattice.sock

Step 3: Configure a Provider

Before using lattice, configure an LLM provider:

bash
# Option 1: Anthropic Claude (requires API key from console.anthropic.com)
ada config provider set anthropic --api-key sk-your-key-here

# Option 2: OpenAI (requires API key from platform.openai.com)
ada config provider set openai --api-key sk-your-key-here

# Option 3: Local model with Ollama (free and private)
# First install: brew install ollama
ollama pull mistral
ada config provider set ollama --base-url http://localhost:11434

Step 4: Try Your First Chat

bash
# Start an interactive chat session
ada chat

# Type your message at the prompt
# Your: What is lattice?

Manual Installation (If Script Fails)

Download Binary

bash
# Create the installation directory
mkdir -p ~/.lovelace/lattice/bin

# Download the appropriate binary for your architecture
# For Apple Silicon (M1, M2, M3, etc):
curl -L https://github.com/lovelace-ai/lattice/releases/latest/download/lattice-darwin-arm64 \
  -o ~/.lovelace/lattice/bin/lattice-ctl

# For Intel Mac:
curl -L https://github.com/lovelace-ai/lattice/releases/latest/download/lattice-darwin-amd64 \
  -o ~/.lovelace/lattice/bin/lattice-ctl

# Make executable
chmod +x ~/.lovelace/lattice/bin/lattice-ctl

# Create symlink to bin
sudo ln -sf ~/.lovelace/lattice/bin/lattice-ctl /usr/local/bin/lattice-ctl

Set Up launchd Service

Create the launchd plist file:

bash
cat > ~/Library/LaunchAgents/com.lovelace.lattice.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.lovelace.lattice</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/lattice-ctl</string>
    <string>daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/var/log/lattice.log</string>
  <key>StandardErrorPath</key>
  <string>/var/log/lattice.error.log</string>
</dict>
</plist>
EOF

# Load the service
launchctl load ~/Library/LaunchAgents/com.lovelace.lattice.plist

Verify it loaded:

bash
launchctl list | grep lattice
# Should show the service

macOS-Specific Issues

Gatekeeper Warning (Unsigned Binary)

On older Macs, you might see "cannot be opened because the developer cannot be verified":

bash
# Allow the binary
xattr -d com.apple.quarantine ~/.lovelace/lattice/bin/lattice-ctl

Or open System Preferences → Security & Privacy → Allow lattice-ctl

Apple Silicon (M1/M2/M3) Compatibility

If you see "bad CPU type in executable":

  • Make sure you downloaded the ARM64 version
  • Check your architecture: uname -m (should show arm64)

"Permission denied" errors

If you get permission errors when starting:

bash
# Fix directory permissions
chmod 755 ~/.lovelace/lattice/
chmod 644 ~/.lovelace/lattice/config.toml

# Or run with sudo (temporary workaround)
sudo lattice-ctl start

Daemon won't stay running

If the daemon keeps stopping:

bash
# Check the log
cat /var/log/lattice.log

# Try running manually to see errors
lattice-ctl daemon --verbose

Service Management

bash
# Check if daemon is running
lattice-ctl ping

# Check daemon status details
lattice-ctl daemon status

# Start daemon
lattice-ctl daemon start

# Stop daemon
lattice-ctl daemon stop

# Disable auto-start (keep installed but don't run on boot)
launchctl unload ~/Library/LaunchAgents/com.lovelace.lattice.plist

# Re-enable auto-start
launchctl load ~/Library/LaunchAgents/com.lovelace.lattice.plist

Uninstalling

To completely remove Lattice from macOS:

bash
# Stop the daemon
lattice-ctl daemon stop

# Unload from launchd
launchctl unload ~/Library/LaunchAgents/com.lovelace.lattice.plist

# Remove files
rm /usr/local/bin/lattice-ctl
rm -rf ~/.lovelace/lattice/
rm ~/Library/LaunchAgents/com.lovelace.lattice.plist

Updating

To update to the latest version:

bash
# Re-run the installation script
curl -fsSL https://uselovelace.com/lattice/install.sh | sh

# The daemon will be replaced
# Running agents will persist across updates

Troubleshooting

"Connection refused" when using lattice commands

bash
# Check if daemon is running
lattice-ctl daemon status

# If not running, start it
lattice-ctl daemon start

# Verify daemon is responsive
lattice-ctl ping

"Command not found: lattice-ctl"

bash
# Check if it's in PATH
which lattice-ctl

# If not, verify installation
ls -la /usr/local/bin/lattice-ctl

# Reload shell configuration
source ~/.zshrc  # or ~/.bashrc if using bash

# Check your shell
echo $SHELL

"Darwin/macOS version too old"

Lattice requires macOS 13+. Check your version:

bash
sw_vers

# Or
system_profiler SPSoftwareDataType

If you're on macOS 12 or earlier, you'll need to upgrade your OS.

Socket permission errors

bash
# Check socket location
ls -la /var/folders/*/lattice.sock

# Fix permissions
chmod 600 /var/folders/*/lattice.sock

Getting Help