Guides

Learn to build with
Spindrel.

From first deployment to advanced orchestration patterns. These guides cover every aspect of running your agent fleet.

Quick Start

Up and running in 5 minutes.

Clone, configure, and deploy with Docker Compose. The setup wizard handles the rest.

git clone https://github.com/spindrel-dev/spindrel.git
cd spindrel
./setup.sh                  # interactive setup wizard
docker compose up           # start all services

Requires: Docker, Python 3.12+ (with pip), and git. The wizard configures your LLM provider, web search, and API auth.

All Guides

Deep dives into every feature.

Getting Started

Clone the repo, run the setup wizard, and have your first bot responding in minutes. Covers Docker Compose, environment config, and the admin UI.

quickstartdockersetup

Use Case Recipes

Five concrete recipes for what to build: code review bot, research assistant, project management hub, DevOps monitor, and content creator.

use-casesrecipesexamples

How Spindrel Works

The request flow, context assembly pipeline, tool dispatch, and agent loop — a technical overview of the architecture.

architectureinternalsoverview

Building Integrations

Create custom integrations with routers, dispatchers, hooks, and auto-discovered tools. Follow the three-layer architecture.

integrationspluginsapi

Writing Custom Tools

Add local Python tools with @register, connect MCP servers, and define client-side actions. Understand Tool RAG and pinned tools.

toolsmcppython

Workflows & Automation

Define multi-step workflows in YAML with conditions, approval gates, and cross-bot delegation. Trigger from API, bots, or schedules.

workflowsautomationscheduling

Chat History & Archival

Configure file-based history mode with auto-compaction, memory flush, section indexing, and searchable conversation archives.

historycompactionarchival

Templates & Activation

How integration activation works: carapace injection, template compatibility, and one-click channel setup.

templatesactivationcarapaces

Heartbeats & Scheduling

Configure periodic autonomous check-ins and scheduled tasks. Quiet hours, repetition detection, dispatch modes, and recurrence.

heartbeatstasksscheduling

Delegation & Harnesses

Set up bot-to-bot delegation with orchestrator patterns. Configure external harnesses like Claude Code and Cursor.

delegationharnessesorchestration

Slack Integration

Socket Mode setup, passive memory, multi-bot channels, emoji reactions, and file sharing.

slackmessagingintegration

Secrets & Redaction

How secret detection, the encrypted vault, and automatic redaction protect sensitive data from the LLM.

securitysecretsredaction

Usage & Billing

Per-bot cost tracking, budget limits, spend forecasting, and prompt caching discounts.

usagecostsbilling

Glossary

Key concepts.

Bot

A configured AI agent with its own model, persona, tools, skills, and memory. Defined in YAML.

Channel

A persistent conversation container with a bot assignment, workspace, integration bindings, and optional overrides.

Carapace

A composable bundle of skills, tools, and behavioral instructions that gives a bot domain expertise.

Skill

A Markdown knowledge document that can be pinned, RAG-matched, or fetched on-demand by the bot.

Workspace

A per-channel or per-bot file store with active files, archives, and data directories.

Workflow

A multi-step automation defined in YAML with conditions, approval gates, and cross-bot delegation.

Heartbeat

A periodic autonomous prompt that fires on a schedule — for monitoring, digests, or proactive check-ins.

Delegation

Bot-to-bot task handoff — immediate (synchronous) or deferred (background task).

Integration

A pluggable module connecting Spindrel to external services: Slack, GitHub, Discord, etc.

MCP Server

A remote tool endpoint implementing the Model Context Protocol, proxied transparently by Spindrel.

Learn to build withSpindrel.