Installation

Prerequisites

Before installing Shannon, ensure you have:

Docker (20.10+) and Docker Compose (v2.0+)
Git for cloning the repository
LLM API Key (OpenAI, Anthropic, or other supported provider)
At least 4GB RAM available for Docker

Shannon works on Linux, macOS, and Windows (with WSL2). All examples assume a Unix-like environment.

One-Command Setup

Shannon provides a streamlined setup process that gets you running in minutes:

# Clone the repository
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon

# Initialize configuration and generate protocol buffers
make setup

Tip: make setup is the one‑stop setup (creates .env and generates protobufs). If you only need the environment file, use make setup-env. You can also regenerate protobufs anytime with make proto.

# Add your LLM API key
echo "OPENAI_API_KEY=sk-your-key-here" >> .env

# Download Python WASI interpreter (required for sandboxed execution)
./scripts/setup_python_wasi.sh

# Start all services
make dev

That’s it! Shannon is now running with all required services.

What Gets Installed

The make dev command starts the following services via Docker Compose:

Service	Port	Description
Gateway	8080	REST API gateway
Orchestrator	50052	gRPC orchestration service
Agent Core	50051	Rust-based agent execution
LLM Service	8000	Python LLM provider gateway
Playwright Service	8002	Browser automation service
PostgreSQL	5432	Persistent storage
Redis	6379	Caching and pub/sub
Qdrant	6333	Vector database
Temporal	7233	Workflow engine
Temporal UI	8088	Workflow visualization

The setup script also installs synthesis templates (7 templates for research reports, domain analysis, etc.) and workflow templates (8 example YAML workflows for common task patterns). See Templates for details.

Verify Installation

Check that all services are running:

# View service status
docker compose ps

# All services should show "healthy" or "running"

Test the API:

# Submit a simple task
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is 2+2?"
  }'

# You should receive a response with a task_id

Access the UI

Open your browser and tools as needed:

Shannon Desktop App: see Desktop Application for installation and usage
Temporal UI: http://localhost:8088

Configuration

Shannon is pre-configured for local development, but you can customize it:

Environment Variables

The .env file (created by make setup) contains key configuration:

# LLM Provider Keys
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Service Configuration
GATEWAY_SKIP_AUTH=1  # Disable auth for development
LOG_LEVEL=info

# Database
POSTGRES_USER=shannon
POSTGRES_PASSWORD=shannon_dev
POSTGRES_DB=shannon

# Redis
REDIS_URL=redis://redis:6379

In production, set GATEWAY_SKIP_AUTH=0 to enable API key authentication.

Configuration Files

Advanced configuration is available in the config/ directory:

shannon.yaml - Main system configuration
features.yaml - Feature flags
models.yaml - LLM provider pricing and routing

Common Issues

Port conflicts

If you see port binding errors, check that ports 8080, 50051, 50052, 8000, etc. are not in use:

# macOS/Linux
lsof -i :8080

# Stop conflicting services or change ports in docker-compose.yml

Docker memory issues

Shannon requires at least 4GB RAM. Increase Docker’s memory limit:

Docker Desktop: Settings → Resources → Memory (set to 6GB+)
Linux: Docker uses all available memory by default

Python WASI download fails

If setup_python_wasi.sh fails, manually download:

mkdir -p wasm-interpreters
cd wasm-interpreters
wget https://github.com/vmware-labs/webassembly-language-runtimes/releases/download/python%2F3.11.4%2B20230714-11be424/python-3.11.4.wasm

Services won't start

Check Docker logs for errors:

docker compose logs orchestrator
docker compose logs agent-core
docker compose logs llm-service

Common causes:

Missing .env file (run make setup)
Invalid API keys
Insufficient Docker resources

Next Steps

Now that Shannon is running:

Submit Your First Task

Learn how to interact with Shannon

Core Concepts

Understand agents and workflows

Development Setup

Run core dependencies via Docker, then run services locally to iterate:

# Terminal 1: Start dependencies only (DB, cache, vector, Temporal)
docker compose -f deploy/compose/docker-compose.yml up -d postgres redis qdrant temporal

# Terminal 2: Run Orchestrator locally (gRPC 50052, admin 8081)
cd go/orchestrator
go run ./cmd/server

# Terminal 3: Run Agent Core locally (gRPC 50051)
cd ../../rust/agent-core
cargo run

# Terminal 4: Run LLM Service locally (HTTP 8000)
cd ../../python/llm-service
pip install -r requirements.txt
python main.py

# (Optional) Terminal 5: Run Gateway locally (REST 8080)
cd ../../go/orchestrator/cmd/gateway
go run .

See the Architecture Overview for system architecture details.

Getting Started

Core Concepts

Guides

Prerequisites

One-Command Setup

What Gets Installed

Verify Installation

Access the UI

Configuration

Environment Variables

Configuration Files

Common Issues

Next Steps

Submit Your First Task

Core Concepts

Development Setup

​Prerequisites

​One-Command Setup

​What Gets Installed

​Verify Installation

​Access the UI

​Configuration

​Environment Variables

​Configuration Files

​Common Issues

​Next Steps

Submit Your First Task

Core Concepts

​Development Setup

Prerequisites

One-Command Setup

What Gets Installed

Verify Installation

Access the UI

Configuration

Environment Variables

Configuration Files

Common Issues

Next Steps

Development Setup