curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.3.1/scripts/install.sh | bash

cd ~/shannon # or your install directory nano .env # edit API keys docker compose -f docker-compose.release.yml down docker compose -f docker-compose.release.yml up -d

# Submit a task curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "What is the capital of France?",  "session_id": "demo-session"  }' # Response: {"task_id":"task-dev-123","status":"running"} # Stream events in real-time curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123" # Get final result curl "http://localhost:8080/api/v1/tasks/task-dev-123"

pip install shannon-sdk

cd desktop npm install npm run tauri:build # Builds for your platform

# In a new terminal (backend should already be running) cd desktop npm install npm run dev # Open http://localhost:3000 in your browser

# Web Search (choose one provider) WEB_SEARCH_PROVIDER=serpapi # serpapi | searchapi | google | bing | exa SERPAPI_API_KEY=your-serpapi-key # serpapi.com # OR SEARCHAPI_API_KEY=your-searchapi-key # searchapi.io # OR GOOGLE_SEARCH_API_KEY=your-google-key # Google Custom Search GOOGLE_SEARCH_ENGINE_ID=your-engine-id # Web Fetch/Crawl (for deep research) WEB_FETCH_PROVIDER=firecrawl # firecrawl | exa | python FIRECRAWL_API_KEY=your-firecrawl-key # firecrawl.dev (recommended for production)

# Drop-in replacement for OpenAI API export OPENAI_API_BASE=http://localhost:8080/v1 # Your existing OpenAI code works unchanged

# Monitor agent execution in real-time (SSE) curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123" # Events include: # - WORKFLOW_STARTED, WORKFLOW_COMPLETED # - AGENT_STARTED, AGENT_COMPLETED # - TOOL_INVOKED, TOOL_OBSERVATION # - LLM_PARTIAL, LLM_OUTPUT

# List available skills curl http://localhost:8080/api/v1/skills # Execute task with a skill (skill becomes system prompt) curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Review the auth module for security issues",  "skill": "code-review",  "session_id": "review-123"  }'

# Agents execute code in isolated WASI sandboxes — no network, read-only FS # Each session gets its own workspace at /tmp/shannon-sessions/{session_id}/ curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Run this Python script and save the output",  "session_id": "my-workspace"  }'

# Multi-agent research with automatic synthesis curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Compare renewable energy adoption in EU vs US",  "context": {  "force_research": true,  "research_strategy": "deep"  }  }' # Orchestrates multiple research agents and synthesizes findings with citations

# Multi-agent collaboration with P2P message passing curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Analyze this dataset from multiple perspectives",  "context": {  "force_swarm": true  }  }' # Lead Agent plans and coordinates; worker agents execute via shared workspace

# Tasks can pause for human approval before sensitive operations curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Update the production database schema",  "context": {  "require_approval": true  }  }' # Workflow pauses and waits for explicit human approval before proceeding

# Multi-turn conversations with context memory curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query": "What is GDP?", "session_id": "econ-101"}' # Follow-up remembers previous context (within history window) curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query": "How does it relate to inflation?", "session_id": "econ-101"}' # Agent recalls recent conversation history from the same session

# Run tasks on a schedule (cron syntax) curl -X POST http://localhost:8080/api/v1/schedules \ -H "Content-Type: application/json" \ -d '{  "name": "Daily Market Analysis",  "cron_expression": "0 9 * * *",  "task_query": "Analyze market trends",  "max_budget_per_run_usd": 0.50  }'

# Production agent failed? Replay it locally step-by-step ./scripts/replay_workflow.sh task-prod-failure-123 # Output shows every decision, tool call, and state change

curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{  "query": "Generate a market analysis report",  "config": {  "budget": {  "max_tokens": 5000,  "fallback_model": "gpt-5-mini"  }  }  }' # Automatically switches to cheaper model when 80% budget consumed

# Python runs in isolated WASI sandbox — no network, read-only FS ./scripts/submit_task.sh "Execute Python: import os; os.system('rm -rf /')" # Result: OSError - system calls blocked by WASI sandbox

# Check all services docker compose -f deploy/compose/docker-compose.release.yml ps # Gateway health curl http://localhost:8080/health # Admin health curl http://localhost:8081/health

# All services docker compose -f deploy/compose/docker-compose.release.yml logs -f # Specific service docker compose -f deploy/compose/docker-compose.release.yml logs -f orchestrator docker compose -f deploy/compose/docker-compose.release.yml logs -f gateway docker compose -f deploy/compose/docker-compose.release.yml logs -f llm-service

# Clone the repository git clone https://github.com/Kocoro-lab/Shannon.git cd Shannon # Setup development environment make setup # Creates .env, generates proto files echo "OPENAI_API_KEY=sk-..." >> .env # Add your API key ./scripts/setup_python_wasi.sh # Download Python WASI interpreter (~20MB) # Start all services (builds locally) make dev # Run tests make smoke # E2E smoke tests make ci # Full CI suite

cd Shannon cp .env.example .env nano .env # Add your API keys docker compose -f deploy/compose/docker-compose.release.yml up -d

make lint # Run linters (Go, Rust, Python) make fmt # Format code make proto # Regenerate proto files make logs # View service logs make ps # Service status make down # Stop all services