Installation Guide#

Complete setup instructions for solstone on Linux and macOS.

Prerequisites#

• Python 3.10 or later
• uv (Python package manager)
• Git
• ffmpeg (for audio processing)

Linux (Fedora/RHEL)#

sudo dnf install python3 git ffmpeg pipewire gstreamer1-plugins-base gstreamer1-plugin-pipewire pulseaudio-utils
curl -LsSf https://astral.sh/uv/install.sh | sh

Linux (Ubuntu/Debian)#

sudo apt install python3 git ffmpeg pipewire gstreamer1.0-tools gstreamer1.0-pipewire pulseaudio-utils
curl -LsSf https://astral.sh/uv/install.sh | sh

Linux (Arch)#

sudo pacman -S python git ffmpeg pipewire gstreamer gst-plugin-pipewire libpulse
curl -LsSf https://astral.sh/uv/install.sh | sh

macOS#

xcode-select --install  # Command line tools
brew install python git ffmpeg uv

Installation#

1. Clone and install:

git clone https://github.com/solpbc/solstone.git
cd solstone
make install

This creates an isolated virtual environment in .venv/ and symlinks the sol command to ~/.local/bin/sol. Your system Python remains untouched.

To uninstall:

make uninstall

2. Your journal lives at journal/ inside the solstone directory. It's created automatically on first run.

API Keys#

solstone requires API keys for AI services. All keys are configured in journal/config/journal.json — this is the only key configuration method.

Create the config file:

mkdir -p journal/config
cat > journal/config/journal.json << 'EOF'
{
  "convey": {
    "password": "your-password-here"
  },
  "env": {
    "GOOGLE_API_KEY": "your-key-here"
  }
}
EOF
chmod 600 journal/config/journal.json

Replace your-password-here with a password for the web interface, and your-key-here with your Google AI API key.

Google AI (Gemini) - Required#

Primary backend for transcription, vision analysis, and insights.

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Add the key to the env section of journal/config/journal.json

OpenAI (Optional)#

Alternative backend for chat and agents. Add "OPENAI_API_KEY": "your-key" to the env section.

Anthropic (Optional)#

Alternative backend for chat and agents. Add "ANTHROPIC_API_KEY": "your-key" to the env section.

Rev.ai for Imports (Optional)#

For transcribing imported audio files. Sign up at Rev.ai, get a token from Access Token, and add "REVAI_ACCESS_TOKEN": "your-token" to the env section.

Example with multiple providers#

{
  "convey": {
    "password": "your-password"
  },
  "env": {
    "GOOGLE_API_KEY": "your-gemini-key",
    "OPENAI_API_KEY": "your-openai-key",
    "ANTHROPIC_API_KEY": "your-anthropic-key"
  }
}

Important: journal.json contains your API keys and password. It should always have restricted permissions (chmod 600).

First Run#

Install as a Background Service#

The recommended way to run solstone is as a system service that starts automatically on login:

make install-service

This installs, enables, and starts a systemd user service (Linux) or launchd agent (macOS) with convey on port 5015. To use a custom port:

make install-service PORT=8000

Manage the service with:

sol service status     # Check if running
sol service restart    # Restart
sol service stop       # Stop
sol service logs -f    # Follow logs
sol up                 # Install + start (if not already)
sol down               # Stop

Start Manually (Development)#

For development, run the supervisor directly in a terminal:

sol supervisor         # Auto-selects an available port
sol supervisor 8000    # Use a specific port

This starts:

• Sense - File detection and processing dispatch
• Callosum - Message bus for inter-service communication
• Cortex - Agent execution

Verify Services#

Check that services are running:

sol health

Web Interface#

Access the Interface#

Open the Convey URL shown in the terminal (port is dynamically assigned) and log in with your password.

Configure Your Identity#

After logging in:

1. Click the Settings app in the left menu (gear icon)
2. Fill in your identity information:
   • Full Name - Your legal name
   • Preferred Name - How you want to be addressed
   • Pronouns - Select from dropdown
   • Timezone - Auto-detected, adjust if needed

This helps the system identify you in transcripts and personalize AI responses.

Health Check#

Verify everything is working:

# Check services are running
pgrep -af "sol:sense|sol:supervisor"

# Check Callosum socket exists
ls -la journal/health/callosum.sock

# View service logs
tail -f journal/health/*.log

See DOCTOR.md for troubleshooting.

Observers#

Observers capture screen and audio and upload to the solstone server. Each platform has its own standalone observer. Packages are not yet on PyPI — install from source.

Linux Observer#

git clone https://github.com/solpbc/solstone-linux.git
cd solstone-linux
pipx install --system-site-packages .
solstone-linux setup
solstone-linux install-service

--system-site-packages is required for PyGObject/GStreamer access.

Note: Activity detection (idle, lock, power save) requires GNOME desktop. Other desktops: capture works but activity-based segment boundaries won't trigger.

tmux Observer#

git clone https://github.com/solpbc/solstone-tmux.git
cd solstone-tmux
pipx install .
solstone-tmux setup
solstone-tmux install-service

macOS Observer#

See solstone-macos — requires Xcode (full IDE, not just CLI tools).

Next Steps#

• Create your first facet (project/context) in the web interface
• Review captured content in the Calendar and Transcripts apps
• Chat with the AI about your journal content

For development setup, see AGENTS.md.