Skip to main content

​
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:
ServicePortDescription
Gateway8080REST API gateway
Orchestrator50052gRPC orchestration service
Agent Core50051Rust-based agent execution
LLM Service8000Python LLM provider gateway
Playwright Service8002Browser automation service
PostgreSQL5432Persistent storage
Redis6379Caching and pub/sub
Qdrant6333Vector database
Temporal7233Workflow engine
Temporal UI8088Workflow 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:

​
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

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
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
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
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.