Run Wingman bot locally with live streaming support.
- Python 3.11+ (for local bot development)
- Docker & Docker Compose (for services)
- Slack workspace with admin access
- OpenRouter or OpenAI API key
If you already have a Slack app:
- Go to api.slack.com/apps → select your app
- Get Bot Token: OAuth & Permissions → Bot User OAuth Token (xoxb-...)
- Get App Token: Basic Information → App-Level Tokens → Generate (xapp-...)
- Get Signing Secret: Basic Information → Signing Secret
# 1. Go to https://api.slack.com/apps and create a new app
# 2. Name it "Wingman-dev" for local testingRequired Scopes (OAuth & Permissions):
app_mentions:read
channels:history
channels:read
chat:write
im:history
im:read
im:write
users:read
Enable Socket Mode (Basic Information):
- Toggle Socket Mode ON
- Generate App-Level Token with
connections:writescope
Enable Events (Event Subscriptions):
- Toggle ON
- Subscribe to:
app_mention,message.im
cd wingman
cp .env.example .envEdit .env:
# Required Slack Tokens
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret
# AI Provider (choose one)
OPENROUTER_API_KEY=sk-or-your-key
# OR
OPENAI_API_KEY=sk-your-key
# Model
LLM_MODEL=openai/gpt-4-turbo-preview
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000docker compose up -d postgres chromaVerify:
docker compose psmise run dev-botcd backend
uv sync
python run_bot.py# Check logs
docker compose logs -f bot
# Or if running directly, you should see:
# INFO:slack_bolt.adapter.socket_mode.base_socket_mode:Starting Socket Mode handler...- Open Slack DM to @Wingman
- Send:
Hello! - You should see streaming thinking steps appear
- Invite bot:
/invite @Wingman - Post:
@Wingman what's the status? - Watch the streaming response
- Type:
/wingman hello
When streaming is working, you should see:
🧠 Processing your request...
✅ Analyzing question...
🔍 Searching knowledge base...
✅ Searching knowledge base...
✍️ Generating response...
✅ Generating response...
[Full answer appears here]
The thinking steps show the bot's reasoning process in real-time.
# Check bot logs
docker compose logs -f bot
# Common fixes:
# 1. Verify SLACK_BOT_TOKEN starts with xoxb-
# 2. Verify SLACK_APP_TOKEN starts with xapp-
# 3. Verify Socket Mode is enabled in Slack app settings
# 4. Verify Event Subscriptions are configured-
Verify slack-sdk version is 3.40.0+:
pip show slack-sdk | grep Version -
Check streaming is enabled in your Slack app:
- App settings → Socket Mode → should be ON
- App settings → Event Subscriptions → should be ON
-
Test with a simple message first
# Reset database
docker compose down -v
docker compose up -d postgres chromaIf ports 5432 or 8001 are in use:
# Edit docker-compose.yaml to change portsWingman uses mise for task management. All tasks are defined in mise.toml.
mise run up # Start all services
mise run down # Stop all services
mise run restart # Restart all services
mise run ps # Show running services
mise run logs # Tail all logs
mise run logs-bot # Tail bot logs
mise run logs-backend # Tail backend logs
mise run logs-frontend # Tail frontend logs
mise run clean # Remove containers and volumesmise run dev-backend # Run backend API locally (port 8000)
mise run dev-bot # Run bot locally (with streaming)
mise run dev-frontend # Run frontend locally (port 3000)mise run install # Install all dependencies
mise run install-backend # Install backend deps (uv sync)
mise run install-frontend # Install frontend deps (bun install)mise run migrate # Run pending migrations
mise run migrate-down # Rollback last migration
mise run migrate-create # Create new migration (set MIGRATION_MESSAGE=...)
mise run migrate-history # Show migration history
mise run migrate-current # Show current version
mise run shell-db # Open PostgreSQL shellmise run test # Run all tests
mise run test-backend # Run backend tests
mise run test-frontend # Run frontend testsmise run tf-init # Initialize Terraform
mise run tf-plan # Plan changes
mise run tf-apply # Apply changes (creates Slack app)
mise run tf-destroy # Destroy resources
mise run tf-output # Show outputs
mise run tf-credentials # Show Slack credentials (sensitive!)
mise run tf-sync-vars # Sync .env → Terraform Cloud
mise run tf-load-vars # Load Terraform Cloud → .env
mise run tf-oauth-url # Show OAuth install URLmise tasks# Terminal 1: Backend API
mise run dev-backend
# Terminal 2: Bot (with streaming)
mise run dev-bot
# Terminal 3: Frontend
mise run dev-frontend# For Docker deployment
docker compose up -d --build bot
# For local
cd backend && uv syncGET /api/documents accepts an optional q parameter to search document titles
and full content for a case-insensitive literal substring. Surrounding whitespace
is ignored; an omitted or blank query returns the usual list. Characters such as
% and _ are literal text, not search wildcards.
curl -sS --get http://localhost:8000/api/documents \
--data-urlencode 'q=VPN' \
--data-urlencode 'source=api' \
--data-urlencode 'limit=10' \
--data-urlencode 'offset=0'Search and source filters combine before counting and pagination. The response
keeps the existing items, total, limit and offset fields and newest-first
ordering. A search with no matches returns an empty page with total set to zero. This searches
saved PostgreSQL records and does not call Slack, embeddings or the model.
In the dashboard, open Documents, enter text in Search documents and submit Search. Results are paginated in groups of 20; Previous and Next keep the submitted search. Clear search returns to the first page of all saved documents. Typing does not send a request until the form is submitted. Selecting a result displays its full saved content.
- Full Setup Guide - Complete deployment instructions
- Slack Auth Reference - Token details and security
- Getting Started - Quick start overview