# Frequently Asked Questions (FAQ) Answers to common questions about Gorkbot. --- ## General Questions ### Q: What is Gorkbot? Gorkbot is an AI orchestration platform that integrates multiple AI providers (Grok, Gemini, Claude, OpenAI) into a single intelligent interface with reasoning layers, tool execution, and cross-session memory. ### Q: How is Gorkbot different from ChatGPT? | Feature | Gorkbot | ChatGPT | |---------|---------|---------| | **Multi-provider** | ✅ Yes | ❌ No (OpenAI only) | | **Local execution** | ✅ Terminal + Web | ❌ Web only | | **Tool execution** | ✅ 28+ tools | ❌ Limited | | **Reasoning engines** | ✅ SPARK, SRE, etc. | ❌ Single model | | **Memory** | ✅ Cross-session | ❌ Current session only | | **Custom tools** | ✅ DIY tool creator | ❌ No | | **Open source** | ✅ MIT License | ❌ Proprietary | ### Q: What providers are supported? - ✅ **Grok (xAI)** - grok-2, grok-2-1212 - ✅ **Gemini (Google)** - gemini-2-flash, gemini-1.5-pro - ✅ **Claude (Anthropic)** - claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5 - ✅ **OpenAI (GPT)** - gpt-4-turbo, gpt-4o - ✅ **OpenRouter** - 100+ models via unified API - ✅ **Minimax** - Chinese LLM - ✅ **Moonshot** - 200K context window - ✅ **Any OpenAI-compatible API** ### Q: Is Gorkbot free? Gorkbot itself is free (MIT license). However: - API calls to providers are paid (varies by provider) - Free tiers available: Gemini, Anthropic have free credits - Pay-as-you-go: xAI, OpenAI charge per token ### Q: Can I run Gorkbot offline? Partially: - ✅ Local conversation history, tools, reasoning - ❌ LLM calls require internet connection - ⚠️ Native LLM support (llamacpp) coming soon --- ## Setup & Installation ### Q: How do I get API keys? **Grok (xAI)**: 1. Go to https://console.x.ai/ 2. Create account (email required) 3. Click "API Keys" → "Generate API Key" 4. Copy key (starts with `xai-`) **Gemini (Google)**: 1. Go to https://aistudio.google.com/apikey 2. Click "Create API Key" 3. Free tier available! **Claude (Anthropic)**: 1. Go to https://console.anthropic.com/ 2. Create account 3. API Keys section → Create Key **OpenAI**: 1. Go to https://platform.openai.com/api-keys 2. Create account/sign in 3. "$5 free credits" available ### Q: Do I need all API keys? No! You need at least ONE: - Grok: Recommended (default) - Gemini: Free tier available - Claude: Good alternative - OpenAI: Optional ### Q: How do I set API keys? **Option 1**: Interactive setup (recommended) ```bash ./gorkbot setup ``` **Option 2**: Environment variables ```bash export XAI_API_KEY=xai-xxx ./gorkbot ``` **Option 3**: .env file ```bash echo "XAI_API_KEY=xai-xxx" > .env ./gorkbot ``` ### Q: Is my API key safe? Yes: - ✅ Keys never sent to Gorkbot servers - ✅ Only sent to official provider APIs - ✅ Stored in `.env` (gitignored by default) - ✅ Can enable encryption: `./gorkbot setup` - ✅ File permissions: 0600 (user only) --- ## Usage ### Q: How do I switch models? In TUI: ``` /model # Select from list ``` Or via command line: ```bash ./gorkbot -model grok-2-1212 ``` Or in config (`~/.config/gorkbot/app_state.json`): ```json { "primary_model": "grok-2" } ``` ### Q: How do I enable extended thinking? ```bash ./gorkbot -thinking-budget 5000 ``` Or in TUI (if supported by model): ``` /settings → Thinking Budget: 5000 ``` **Note**: Only Claude 3.5+ and Grok support extended thinking. ### Q: Can I use multiple providers? Yes! Configure: - **Primary**: Main model for responses - **Secondary/Consultant**: For complex reasoning Switch in TUI: ``` /model ``` Gorkbot automatically fails over if primary is unavailable. ### Q: What tools are available? ``` /tools ``` 28+ tools including: - Bash command execution - File operations (read, write, list) - Git operations - Web fetching - System info - Security tools (nmap, nuclei) - And more! ### Q: Can I create custom tools? Yes! Use the `create_tool` meta-tool: ``` > Create a tool that pings a host Gorkbot will: 1. Ask for tool name, description, parameters 2. Generate complete tool code 3. Save to ~/.config/gorkbot 4. Available immediately ``` --- ## Performance & Optimization ### Q: Why is Gorkbot slow? Possible causes: 1. **Network latency**: Provider API is slow - Try different provider: `/model` - Check internet: `ping google.com` 2. **Large history**: Conversation too long - Compress: `/compress` - Clear: `/clear` 3. **Tool execution**: Tool command is slow - Check logs: `~/.config/gorkbot/gorkbot.json` - Enable debug: `-debug-mcp` 4. **Context limits**: Token limit exceeded - Compress history: `/compress` - Start new session: `/clear` ### Q: How can I make Gorkbot faster? 1. **Use cache**: Enables by default 2. **Disable verbose**: `/verbose off` 3. **Compress regularly**: `/compress` 4. **Use Grok**: Generally faster than alternatives 5. **Upgrade providers**: Use newer models (grok-2 > grok-1) ### Q: How much do API calls cost? Varies by provider: | Provider | Cost | Free Tier | |----------|------|-----------| | Grok | ~$0.02/1K input tokens | $5 free | | Gemini | Free - $0.075/1K | ✅ Free | | Claude | ~$0.003/1K input | Free credits | | GPT-4o | ~$0.015/1K input | $5 free | **Typical session** (~5K tokens input, 10K output): - Grok: ~$0.15-0.20 - Gemini (free): $0 - Claude: ~$0.02 - GPT-4o: ~$0.20 --- ## Troubleshooting ### Q: "Invalid API Key" error **Solutions**: 1. Check key format ```bash echo $XAI_API_KEY # Should start with xai- ``` 2. Check for whitespace ```bash echo "$XAI_API_KEY" | od -c # Look for spaces ``` 3. Regenerate key from provider website 4. Run setup again: `./gorkbot setup` ### Q: "Connection refused" **Solutions**: 1. Check internet: `ping google.com` 2. Check firewall: May block API calls 3. Try VPN: Some networks block external APIs 4. Try different provider: `/model` ### Q: "Out of memory" **Solutions**: 1. Compress history: `/compress` 2. Clear session: `/clear` 3. Close other apps 4. Increase system RAM ### Q: "Tool execution failed" **Solutions**: 1. Check tool name: `/tools` 2. Check tool docs: `/tool-info <name>` 3. Enable debug: `-debug-mcp` 4. Check audit log: `gorkbot.db` tool_calls table ### Q: "Context limit exceeded" **Solutions**: 1. Compress history: `/compress` 2. Export and archive old conversations 3. Use shorter prompts 4. Switch to model with larger context (Gemini 200K, Moonshot 200K) --- ## Advanced Questions ### Q: Can I deploy Gorkbot on a server? Yes! Options: 1. **Docker**: Containerized deployment ```bash docker run -it ghcr.io/velariumai/gorkbot:latest ``` 2. **Web UI**: Server mode on port 8080 ```bash ./gorkbot -web -port 8080 ``` 3. **MCP Servers**: Integrate with other tools - 12+ supported servers - Configure in `mcp.json` ### Q: Can I use Gorkbot in CI/CD? Yes! One-shot mode: ```bash # In GitHub Actions ./gorkbot -p "Run tests and report" > output.txt ``` Or programmatically: ```go // Use orchestrator package directly orch.ExecuteTask(ctx, "Run pytest on changes") ``` ### Q: How do I integrate with my project? Options: 1. **GORKBOT.md**: Project-specific instructions - Automatically loaded - Injected into system prompt - Watched for changes 2. **Custom tools**: Create tools for your workflow - `create_tool` to generate - Available immediately 3. **MCP servers**: Connect to project tools - Git integration - Database queries - Custom APIs ### Q: Can I use Gorkbot programmatically? Yes! Import the packages: ```go import ( "github.com/velariumai/gorkbot/internal/engine" "github.com/velariumai/gorkbot/pkg/ai" "github.com/velariumai/gorkbot/pkg/tools" ) // Create orchestrator orch, err := engine.NewOrchestrator(...) // Execute task result, err := orch.ExecuteTask(ctx, "What is 2+2?") ``` --- ## Getting Help - 📖 **Full docs**: [README.md](README.md) - 🆘 **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - 🐛 **Report bugs**: [GitHub Issues](https://github.com/velariumai/gorkbot/issues) - 💬 **Discussions**: [GitHub Discussions](https://github.com/velariumai/gorkbot/discussions) - 📧 **Email**: velarium.ai@gmail.com --- **Still have questions? Open an issue or email us!**