1st Mate (1m)

Personal AI assistant for home lab and small business management. Signal bot powered by an LLM API with Ollama local fallback and a full tool suite for managing a home network.

Features

• Agentic tool loop — LLM calls tools, gets results, and keeps going until it has an answer
• Ollama fallback — drops to local LLM if the API is unavailable
• Session memory — 30-message conversation history per session
• Persistent memory — save/recall facts across restarts

Tools

Tool	Description
ssh_command	Run commands on any machine on the home network
read_file / write_file	Read and write files on the home server
list_directory / search_files	Browse the filesystem
send_email	Send email via msmtp
get_calendar_events	Read Thunderbird calendar (SQLite)
web_search	DuckDuckGo search
fetch_webpage	Fetch and read web page content
github	Manage GitHub repos via gh CLI
save_memory / get_memory	Persistent key-value memory
list_memories / delete_memory	Memory management
get_system_status	System health — uptime, disk, memory
check_service	Check systemd service status
list_docker_containers	List running Docker containers

Stack

• Python 3.12
• signal-cli-rest-api (bbernhard)
• LLM API — default: haiku
• Ollama (llama3.2 fallback)
• Docker + docker-compose

Setup

1. Register your Signal number with signal-cli (one-time)
2. Copy .env.example to .env and fill in your values
3. docker compose up -d --build

Environment Variables

SIGNAL_NUMBER=          # Bot's Signal phone number e.g. +13526918580
ALLOWED_NUMBER=         # Your personal Signal number
SIGNAL_API_URL=         # Default: http://localhost:8080
LLM_API_KEY=            # LLM provider API key
LLM_MODEL=              # Default: claude-haiku-4-5-20251001
OLLAMA_HOST=            # Default: http://127.0.0.1:11434
OLLAMA_MODEL=           # Default: llama3.2
GITHUB_TOKEN=           # GitHub PAT for gh CLI tool
GITHUB_USER=            # Your GitHub username
HOSTS_CONFIG=           # JSON: {"hostname": ["user", "ip"]}
HOST_HOME=              # Host home directory path e.g. /home/sh1pwr3ck

Architecture

Signal → receive_signal_messages() (polling)
              ↓
         handle_message()
              ↓
         run_with_tools()  ← agentic loop (max 8 iterations)
              ↓
         LLM API (tool_use)
              ↓
         execute_tool()  → filesystem / ssh / email / etc.
              ↓
         feed results back → LLM → end_turn → reply
              ↓ (on API failure)
         Ollama fallback (no tools)

---

Built by Jax Jackson / Noble Technologies LLC