Frequently Asked Questions (FAQ)

Common questions and answers about Soothe.

General

What is Soothe?

Soothe is a goal-driven orchestration framework for building 24/7 long-running autonomous agents. It extends LangChain/DeepAgents with:

  • Persistent agentic loop (Plan → Execute iterations)
  • Goal engine for multi-goal orchestration
  • Protocol-first design with pluggable backends
  • Durable execution with crash recovery
  • Security policies and least-privilege delegation

Key difference: Shift from human-in-the-loop to agent-in-the-loop — define intent, let the system handle execution.

What can Soothe do?

Capability Examples
Deep Research Multi-source web search, academic papers (arXiv, DeepXiv), document analysis
Autonomous Execution Multi-step workflows, file operations, code execution, shell commands
Long-Running Ops Background daemon, thread management, persistent state
Custom Plugins @tool, @subagent, @plugin decorators, MCP server integration

How does Soothe differ from LangChain/LangGraph?

Soothe adds:

  • Goal management: Multi-goal orchestration with goal DAGs
  • Agentic loop: Plan → Execute iterations for complex goals
  • Persistent memory: MemU semantic memory across sessions
  • Durability: Automatic crash recovery and checkpointing
  • Security policies: Config-driven least-privilege
  • Daemon server: WebSocket transports

Built on:

  • LangGraph for agent runtime (CoreAgent)
  • DeepAgents for subagent orchestration
  • LangChain for tools and model abstraction

What Python version is required?

Python 3.11+ is required. Soothe uses modern Python features:

  • Type hints with typing module
  • match/case statements
  • Async improvements
  • Dataclasses and Pydantic v2

Installation

What packages do I need to install?

Recommended (full stack):

pip install -U soothe soothe-cli soothe-daemon

Minimal (core + CLI): pip install soothe soothe-cli

GitHub: use the gh CLI (builtin skill) or MCP (mcp_builtins: [github]); no Python extra required.

See Installation Guide for details.

Why do I need soothe-plugins?

soothe-plugins is a separate package (separate repo) with optional delegated agents such as Weaver and BrowserUse extensions.

Install:

pip install soothe-plugins

Configure (example):

subagents:
  browser_use:
    enabled: true

See soothe-plugins repo for details.

How do I verify installation? 

# Check CLI
soothe --help

# Check daemon
soothed doctor

# Run test query
soothe -p "What is the capital of France?"

Configuration

How do I configure Soothe?

Three methods:

  1. Environment variables: export SOOTHE_<FIELD>=<value>
  2. YAML config file: ~/.soothe/config/config.yml or --config path/to/config.yml
  3. CLI arguments: soothe --debug --config my.yml

See Configuration Guide for complete reference.

How do I set API keys?

Environment variables (recommended):

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_BASE_URL=...  # Optional: for OpenAI-compatible providers

YAML config (with env var interpolation):

providers:
  - name: openai
    provider_type: openai
    api_key: "${OPENAI_API_KEY}"
    models: [gpt-4o-mini]

Secret management (production):

  • Vault
  • AWS Secrets Manager
  • GCP Secret Manager
  • Azure Key Vault

See Configuration Guide - Provider Setup.

How do I choose which model to use?

Use model router to map purpose roles to models:

router_profiles:
  - name: default
    router:
      default: "openai:gpt-4o-mini"   # Main orchestrator
      think: "openai:o3-mini"          # Complex reasoning
      fast: "openai:gpt-4o-mini"       # Classification
      image: "openai:gpt-4o"           # Vision
active_router_profile: default
embedding_profile:
  - model_role: "openai:text-embedding-3-small"
    embedding_dims: 1536

Roles:

  • default: Orchestrator reasoning (CoreAgent)
  • think: Planning, complex reasoning
  • fast: Classification, routing
  • image: Vision/image understanding
  • embedding: Vector operations (MemU)

See Configuration Guide - Model Router.

How do I use local models (Ollama)?

Install Ollama:

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2
ollama serve

Configure Soothe:

providers:
  - name: ollama
    provider_type: ollama
    api_base_url: "http://localhost:11434"
    models: [llama3.2]

router:
  default: "ollama:llama3.2"

See Configuration Guide - Provider Setup.

Usage

How do I run a quick query?

One-shot mode (no TUI):

soothe -p "List Python files in current directory and count lines"

TUI mode (interactive):

soothe
# Opens TUI, type your query

Daemon mode (background):

soothed start
soothe -p "Analyze codebase structure"  # CLI auto-connects to running daemon

How do I enable autonomous mode?

Autonomous mode allows multi-step autonomous execution:

agent:
  autonomous:
    enabled_by_default: true
    max_iterations: 10
    max_retries: 2

Or per-request:

soothe autopilot run "Research AI safety papers and summarize findings"

See Autonomous Mode Guide.

How do I manage conversation threads?

List threads:

soothe loop list

Continue thread:

soothe loop continue <thread-id>

Resume last thread:

soothe loop continue

Thread directory: ~/.soothe/data/threads/<thread-id>/

See Thread Management Guide.

How do I use subagents?

Subagents are specialized helper agents:

Built-in (always available):

  • planner - Planning delegate
  • deep_research - Public web research
  • academic_research - Academic literature research
  • browser_use - Browser automation
  • veritas - Clarification auto-answerer in autonomous mode
  • SkillifyService - Semantic skill search (daemon-shared; configure via skillify:)

Configure:

subagents:
  deep_research:
    enabled: true
    config:
      effort: normal  # normal | thorough
  academic_research:
    enabled: true
    config:
      effort: normal

See Subagents Guide.

Daemon

How do I start the daemon? 

# Start daemon in background
soothed start

# Check status
soothed status

# Stop daemon
soothed stop

# Restart daemon
soothed restart

Foreground mode (debugging):

soothed start --foreground

See Daemon Management Guide.

How do I connect to a running daemon?

CLI connects automatically if daemon is running:

soothe -p "your query"  # CLI auto-connects to daemon on localhost:8765

For a remote daemon, specify host and port:

soothe --daemon-host remote.example.com --daemon-port 8765 -p "your query"

See Transport Guide.

How do I enable WebSocket?

Configure transports in ~/.soothe/config/daemon.yml:

transports:
  websocket:
    enabled: true
    host: "127.0.0.1"
    port: 8765

Start daemon:

soothed start

See Transport Guide.

Deployment

How do I deploy Soothe in production?

Docker Compose (recommended):

cd deploy && cp env-example .env && vim .env && docker compose up -d

See Production Setup for full guide.

How do I monitor Soothe?

Health checks:

soothed doctor
soothed status

Logs:

# Daemon logs
tail -f ~/.soothe/logs/soothed.log

# Thread logs
tail -f ~/.soothe/data/threads/<thread-id>/thread.log

Langfuse (LLM traces):

observability:
  langfuse:
    enabled: true
    public_key: "${LANGFUSE_PUBLIC_KEY}"
    secret_key: "${LANGFUSE_SECRET_KEY}"
    host: "https://cloud.langfuse.com"

See Deployment Guide - Monitoring.

How do I secure Soothe?

Soothe does NOT have built-in authentication. Use reverse proxy:

Client → nginx (Auth + TLS) → Soothe Daemon

Reverse proxy handles:

  • TLS termination (HTTPS/WSS)
  • Authentication (API key, JWT, OAuth)
  • Authorization (RBAC)
  • Rate limiting

See Authentication Guide and Deployment Guide - Security.

Troubleshooting

Why does “Could not resolve model” error occur?

Missing API key:

export OPENAI_API_KEY=sk-...

Invalid model name:

router:
  default: "openai:gpt-4o-mini"  # Check model exists

Provider not configured:

providers:
  - name: openai
    provider_type: openai
    api_key: "${OPENAI_API_KEY}"
    models: [gpt-4o-mini]  # Must list model

See Troubleshooting Guide.

Why does WebSocket connection fail?

Daemon not running:

soothed status
soothed start

WebSocket not enabled:

# ~/.soothe/config/daemon.yml
transports:
  websocket:
    enabled: true

Firewall blocking:

# Check port is open
netstat -an | grep 8765

See Troubleshooting Guide.

Why does subagent not work?

Subagent disabled:

subagents:
  <name>:
    enabled: true  # Must be true

Community subagent not installed:

pip install soothe-plugins

Missing Anthropic provider key:

export ANTHROPIC_API_KEY=sk-ant-...

See Troubleshooting Guide.

How do I debug agent behavior?

Enable debug mode:

soothe --debug "your query"

Enable verbose logging:

SOOTHE_LOG_LEVEL=DEBUG soothe "your query"

Check logs:

tail -f ~/.soothe/logs/soothed.log
tail -f ~/.soothe/data/threads/<thread-id>/thread.log

Langfuse traces:

  • View LLM calls, prompts, responses
  • Track token usage and latency

See Debug Guide and Troubleshooting Guide.

Development

How do I contribute to Soothe?

See Contributing Guide for:

  • Development setup
  • Code standards
  • Pull request process
  • Architecture guidelines

Quick start:

git clone https://github.com/mirasoth/soothe.git
cd soothe
make sync
./scripts/verify_finally.sh

How do I run tests?

See Testing Guide.

Quick commands:

# Unit tests
make test-unit

# Integration tests (requires PostgreSQL)
docker compose -f docker-compose.yml up -d
make test-integration

# Full verification
./scripts/verify_finally.sh

How do I create a custom tool?

Use @tool decorator:

from soothe_sdk.plugin import tool

@tool(name="my_tool", description="Does something")
def my_tool(arg: str) -> str:
    """Custom tool implementation.
    
    Args:
        arg: Input argument.
    
    Returns:
        Tool result.
    """
    return f"Result: {arg}"

Register via plugin:

from soothe_sdk.plugin import plugin

@plugin(name="my-plugin", version="1.0.0")
class MyPlugin:
    @tool(name="my_tool", description="Does something")
    def my_tool(self, arg: str) -> str:
        return f"Result: {arg}"

See Channel Plugin Guide.

How do I create a custom subagent?

Use @subagent decorator:

from soothe_sdk.plugin import subagent
from soothe_deepagents import CompiledSubAgent

@subagent(name="my_agent", description="Custom agent")
async def create_agent(model, config, context):
    """Create custom subagent.
    
    Args:
        model: Chat model instance.
        config: Subagent configuration.
        context: Plugin context.
    
    Returns:
        CompiledSubAgent instance.
    """
    # Build and return CompiledSubAgent
    return CompiledSubAgent(...)

See Channel Plugin Guide.

Architecture

What is the three-level execution model? 

┌─────────────────────────────────────┐
│ ContextEngine: Autonomous Goal Mgmt  │  Goal DAGs, multi-goal orchestration
│ Loop: Goal → PLAN → PERFORM → ...   │
└─────────────────────────────────────┘
              ↓ PERFORM
┌─────────────────────────────────────┐
│ StrangeLoop: Agentic Goal Execution   │  Plan → Execute iterations
│ Loop: Plan → Execute (max ~8 iter) │
└─────────────────────────────────────┘
              ↓ EXECUTE
┌─────────────────────────────────────┐
│ CoreAgent: Runtime                  │  Model → Tools → Model loop
│ Foundation: create_soothe_agent()   │
└─────────────────────────────────────┘

See Architecture Overview.

What protocols does Soothe use?

8 runtime-agnostic protocols:

Protocol Purpose
MemoryProtocol Semantic memory (MemUMemory)
PlannerProtocol Planning strategy (LLMPlanner)
PolicyProtocol Security policies (ConfigDrivenPolicy)
DurabilityProtocol Thread lifecycle (SQLite, PostgreSQL)
AsyncPersistStore Key-value storage (SQLite, PostgreSQL)
VectorStoreProtocol Embedding storage (PGVector, SQLiteVec, Weaviate)
WorkspaceProtocol Workspace resolution and validation

See Architecture Overview - Protocols.

How does the Plan → Execute loop work?

StrangeLoop iterates Plan → Execute:

User Query → StrangeLoop
  ↓
PLAN phase
  - Decompose goal into plan steps
  - Prioritize steps
  ↓
EXECUTE phase
  - Execute steps (tools, subagents)
  - Collect results
  - Check if goal complete
  ↓
If incomplete → PLAN again (adapt plan)
If complete → Return final response

Max iterations: 10 (configurable)

See Architecture Overview - StrangeLoop.

Performance

How do I optimize performance?

LLM rate limiting:

agent:
  loop:
    llm_rate_limit:
      rpm_limit: 120            # Requests per minute
      concurrent_limit: 10      # Concurrent calls

Context window management (RFC-224):

agent:
  loop:
    context_window_limit: 200000
    context_overflow_threshold_pct: 0.80
    context_compaction_target_pct: 0.60

PostgreSQL optimization:

persistence:
  postgres_pool_min_size: 4
  checkpointer_pool_size: 24

Vector store indexes:

vector_stores:
  - name: pgvector
    provider_type: pgvector
    index_type: hnsw  # Fast approximate search

See Deployment Guide - Scaling.

How do I scale Soothe?

Horizontal scaling (multi-node):

Load Balancer (nginx)
  ↓
Soothe Daemon Node 1
Soothe Daemon Node 2
Soothe Daemon Node 3
  ↓
PostgreSQL Cluster (primary + replicas)

Kubernetes:

  • StatefulSet for PostgreSQL
  • Deployment for daemon nodes
  • HPA for auto-scaling

See Deployment Guide - Scaling.

Integration

How do I integrate with MCP servers?

MCP (Model Context Protocol) servers provide external tools:

mcp_servers:
  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    defer: true  # Progressive disclosure

Transports: stdio, sse, streamable_http, websocket

See Configuration Guide - MCP Servers.

How do I integrate with Langfuse?

Langfuse provides LLM observability:

observability:
  langfuse:
    enabled: true
    public_key: "${LANGFUSE_PUBLIC_KEY}"
    secret_key: "${LANGFUSE_SECRET_KEY}"
    host: "https://cloud.langfuse.com"

Local Langfuse (dev):

docker compose -f docker-compose.yml up -d
# UI: http://localhost:3300

See Deployment Guide - Monitoring.

More Questions?