Skip to content

getting-started.md

Latest commit

 

History

History
126 lines (92 loc) · 3.81 KB

getting-started.md

File metadata and controls

126 lines (92 loc) · 3.81 KB

Getting Started

Prerequisites

  • Go 1.24+ — for building from source
  • just — command runner (replaces Makefiles)
  • At least one model provider — Ollama, LM Studio, or an Anthropic API key
  • Home Assistant — with a long-lived access token
  • MQTT broker — typically the Mosquitto add-on in Home Assistant

Thane requires Home Assistant and an MQTT broker. HA is the sensory layer — how Thane perceives and acts in the physical world. MQTT is the telemetry bus — how Thane publishes its own state as HA-discoverable entities. See Philosophy: Why Home Assistant for the reasoning.

Future: Self-managed Home Assistant in a Docker container is on the roadmap for operators who don't already run HA.

Build

git clone https://github.com/nugget/thane-ai-agent.git
cd thane-ai-agent
just build

This builds a platform-specific binary into dist/. Cross-compile with just build linux arm64.

Initialize

Set up the ~/Thane directory with config, talents, and persona:

just init

This creates ~/Thane/config.yaml, copies talent files, and sets up the persona. Edit ~/Thane/config.yaml for your setup.

Required settings:

homeassistant:
  url: http://homeassistant.local:8123
  token: your_long_lived_access_token

mqtt:
  broker: tcp://homeassistant.local:1883

Model providers (configure at least one):

# Local models via Ollama (recommended for delegation)
models:
  ollama_url: http://localhost:11434

# Local models via LM Studio
models:
  lmstudio_url: http://localhost:1234

# Cloud models via Anthropic
anthropic:
  api_key: sk-ant-...

Most operators run a local provider for delegation (cheap, fast tool execution) and optionally add Anthropic for complex reasoning. See Your First Thane for hardware and model sizing guidance.

See Configuration for a guide by concern, or examples/config.example.yaml for the full field reference.

Run

# Start the server
just serve

# Or run the binary directly
~/Thane/bin/thane serve

# Quick test from CLI
~/Thane/bin/thane ask "Hello!"

The server starts three listeners:

  • http://localhost:8080 — Native API (OpenAI-compatible) + operational dashboard
  • http://localhost:11434 — Ollama-compatible API (for Home Assistant)
  • http://localhost:8843 — CardDAV server (for contact sync)

Connect to Home Assistant

  1. In HA: Settings > Devices & Services > Add Integration > Ollama
  2. Set URL to http://thane-host:11434, select model thane:latest
  3. Under Voice Assistants, set conversation agent to the new integration

See Home Assistant for the full integration guide.

Development

All workflows go through just:

just build                    # Build for current platform
just build linux arm64        # Cross-compile
just test                     # Run tests (always with -race)
just ci                       # Full CI gate: fmt + lint + test
just install                  # Install binary to ~/Thane/bin/
just service-install          # Install + enable as system service
just logs                     # Tail live logs

Run just with no arguments to see all available recipes.

Next Steps