cobot 0.2.0

Minimal self-sovereign AI agent with Nostr identity and Lightning wallet

Features • Quick Start • Plugins • Architecture • Contributing

What is Cobot?

Cobot is a lightweight personal AI agent that runs on your hardware, identifies via Nostr, and transacts via Lightning Network.

Unlike cloud-hosted assistants or complex frameworks, Cobot gives you true ownership:

Your keys, your identity, your agent.

┌─────────────────────────────────────┐
│           Your Hardware             │  ← Physical control
├─────────────────────────────────────┤
│          Cobot Runtime              │  ← Self-hosted (~2K lines)
├─────────────────────────────────────┤
│    Nostr Identity (npub/nsec)       │  ← Self-sovereign ID
├─────────────────────────────────────┤
│   Lightning Wallet (npub.cash)      │  ← Self-sovereign money
├─────────────────────────────────────┤
│      LLM (local or cloud)           │  ← Flexible inference
└─────────────────────────────────────┘

Features

Quick Start

Install

git clone https://github.com/ultanio/cobot
cd cobot

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install cobot
pip install -e .

Setup Wizard

The easiest way to configure Cobot is the interactive wizard:

cobot wizard init

The wizard will guide you through:

• Identity — Name your agent
• Provider — Choose your LLM (PPQ, Ollama, etc.)
• Plugins — Configure any installed plugins

This creates a cobot.yml in your current directory.

Run

# Start agent
cobot run

# Interactive mode
cobot run --stdin

# Check status
cobot status

Manual Configuration

If you prefer manual setup, copy and edit the example config:

cp cobot.yml.example cobot.yml
# Edit cobot.yml with your settings

Configuration

# cobot.yml
provider: ppq  # or: ollama

identity:
  name: "MyAgent"

ppq:
  api_key: "${PPQ_API_KEY}"
  model: "gpt-4o"

# Optional: Nostr identity
nostr:
  relays:
    - "wss://relay.damus.io"

# Optional: Lightning wallet
wallet:
  provider: "npub.cash"

# Tool execution
exec:
  enabled: true
  timeout: 30

Plugins

Cobot uses a plugin architecture where functionality is modular and extensible.

Built-in Plugins

Extension Points

Cobot's unique feature: plugins can define extension points that other plugins implement.

┌─────────────┐                    ┌─────────────────┐
│   filedrop  │ ──defines──────►   │ Extension Point │
│   plugin    │                    │ filedrop.verify │
└─────────────┘                    └────────┬────────┘
                                            │
                                   implements
                                            │
                                   ┌────────▼────────┐
                                   │ filedrop-nostr  │
                                   │     plugin      │
                                   └─────────────────┘

Example:

# filedrop defines extension point
meta = PluginMeta(
    id="filedrop",
    extension_points=["filedrop.before_write", "filedrop.after_read"],
)

# filedrop-nostr implements it
meta = PluginMeta(
    id="filedrop-nostr",
    implements={
        "filedrop.before_write": "sign_message",
        "filedrop.after_read": "verify_message",
    },
)

Adding Plugins

Place plugins in one of these directories:

1. System: /opt/cobot/plugins/
2. User: ~/.cobot/plugins/
3. Project: ./plugins/

Each plugin needs a plugin.py with a create_plugin() factory function.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    PLUGIN REGISTRY                           │
│  Registration │ Dependency resolution │ Extension points    │
├─────────────────────────────────────────────────────────────┤
│                      PLUGINS                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ config  │ │   llm   │ │  comms  │ │ wallet  │  ...      │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────────────────────────────────────────┤
│                  EXTENSION POINTS                            │
│         Plugins define hooks → Others implement              │
├─────────────────────────────────────────────────────────────┤
│                   HOOK CHAIN                                 │
│  on_message → transform → llm_call → tool_exec → response  │
├─────────────────────────────────────────────────────────────┤
│                   CORE AGENT                                 │
│            Message loop │ Tool execution                     │
└─────────────────────────────────────────────────────────────┘

Core Concepts

CLI Reference

# Core
cobot run              # Start the agent
cobot run --stdin      # Interactive mode (no Nostr)
cobot status           # Show status
cobot restart          # Restart running agent

# Setup
cobot wizard init      # Interactive setup wizard
cobot wizard plugins   # List plugins with wizard sections

# Configuration
cobot config show      # Show current configuration
cobot config validate  # Validate configuration
cobot config edit      # Edit config in $EDITOR

Why Cobot?

Development

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check cobot/

# Format
ruff format cobot/

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Quick Links

• 🐛 Report a bug
• ✨ Request a feature
• 🔌 Request a plugin

Roadmap

• Container isolation for tool execution
• Smart LLM routing (cost optimization)
• More messaging channels (Telegram, Discord)
• Agent-to-agent protocol
• Nostr relay for agent discovery

License

MIT License — see LICENSE for details.

Links

• Nostr — Decentralized social protocol
• Lightning — Bitcoin payment layer
• npub.cash — Lightning wallet for Nostr

_{Built with ⚡ by agents, for agents}