Documentation

Installation

Install OpenSpry with a single command:

# macOS / Linux
curl -fsSL https://openspry.com/install.sh | bash

# Windows (PowerShell)
irm https://openspry.com/install.ps1 | iex

This creates an isolated environment at ~/.openspry/, installs all dependencies, and adds the openspry command to your PATH.

Requirements

• Python 3.11 or newer
• An API key from any supported LLM provider (OpenAI, Anthropic, Google, or local Ollama)

Launching

# Start the web dashboard (default)
openspry

# Start on a specific port
openspry --port 8080

# Start the CLI REPL instead
openspry --cli

The dashboard opens at http://localhost:7070 by default.

LLM Setup

OpenSpry supports multiple LLM providers. Configure your key directly in the chat dashboard — no environment variables or config files needed:

# OpenAI
set key openai sk-...

# Anthropic
set key anthropic sk-ant-...

# Google Gemini
set key google AIza...

# Ollama (local, free — no key needed)
set key ollama local

You can store keys for multiple providers and switch between them at any time:

# Switch active provider
use openai
use anthropic
use ollama

# See all configured providers
show keys

Keys are persisted to data/settings.json and survive restarts. Environment variables also work as fallbacks:

OPENAI_API_KEY      — OpenAI
ANTHROPIC_API_KEY   — Anthropic
GOOGLE_API_KEY      — Google Gemini

Core concepts

Intents are your goals. They can be:

• Explicit — a one-time task with an optional deadline ("Finish the report by Friday").
• Standing — an ongoing objective with no expiry ("Keep my inbox under 20 unread").

The Kernel Clock ticks every 60 seconds. Each tick recalculates priorities, checks for blocked intents, and emits signals to agents for the top-priority work.

Agents receive signals and advance intents using LLMs and tools. The built-in focal agent is a generalist that can handle any intent.

Memory persists everything. Agent results, observations, and user interactions are stored and searchable.

Tools are capabilities agents can invoke — web search, shell commands, or any installed plugin.

CLI commands

If you run openspry --cli, you get an interactive REPL:

add       — Create a new intent
list      — List all intents sorted by priority
inspect   — Deep-dive into a specific intent
complete  — Mark an intent as satisfied
abandon   — Abandon an intent
tick      — Run one kernel tick manually
run       — Start the continuous kernel clock
serve     — Launch the web dashboard
memory    — Search or browse memory
stats     — System status overview
help      — List commands
quit      — Exit

REST API

The web dashboard exposes a full REST API:

GET  /api/intents              — List all intents
POST /api/intents              — Create an intent
GET  /api/intents/{id}         — Get intent detail
POST /api/intents/{id}/complete — Mark satisfied
POST /api/intents/{id}/abandon  — Abandon
GET  /api/stats                — System statistics
GET  /api/settings             — LLM provider settings
POST /api/settings             — Update provider / API key
GET  /api/memory?q=...         — Search memory
POST /api/tick                 — Force a kernel tick
WS   /ws                       — WebSocket for chat + live updates

Configuration

OpenSpry stores data in ./data/ by default (SQLite database). The kernel tick interval, model selection, and token budgets are configurable in openspry/config.py.

Environment variables:

OPENAI_API_KEY      — OpenAI API key
ANTHROPIC_API_KEY   — Anthropic API key
GOOGLE_API_KEY      — Google Gemini API key
OPENSPRY_PORT       — Dashboard port (default: 7070)

Installing tools

Community tools are Python packages. Install them like any pip package into your OpenSpry environment:

pip install openspry-tool-outlook
pip install openspry-tool-telegram

Installed tools are auto-discovered on startup and made available to all agents.

Want to build your own tool? See the Tool Developer Guide.