From 1b85f60ca06d36229f5befdb78df36814b0a911b Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Thu, 1 May 2025 17:08:10 -0700 Subject: [PATCH] env docs --- docs/swarms/install/env.md | 269 ++++++++++++++++++++----------------- 1 file changed, 142 insertions(+), 127 deletions(-) diff --git a/docs/swarms/install/env.md b/docs/swarms/install/env.md index 8fef856c..cbbad8da 100644 --- a/docs/swarms/install/env.md +++ b/docs/swarms/install/env.md @@ -1,6 +1,4 @@ -# Environment Variable Management & Security - -This guide provides comprehensive documentation for managing environment variables and API keys securely in the Swarms framework. +# Environment Variables ## Overview @@ -10,80 +8,106 @@ Swarms uses environment variables for configuration management and secure creden ### Framework Configuration -- `SWARMS_VERBOSE_GLOBAL`: Controls global logging verbosity - ```bash - SWARMS_VERBOSE_GLOBAL="True" # Enable verbose logging - SWARMS_VERBOSE_GLOBAL="False" # Disable verbose logging - ``` - -- `WORKSPACE_DIR`: Defines the workspace directory for agent operations - ```bash - WORKSPACE_DIR="agent_workspace" - ``` - -### API Keys - -#### Model Provider Keys - -1. **OpenAI** - - `OPENAI_API_KEY`: Authentication for GPT models - ```bash - OPENAI_API_KEY="your-openai-key" - ``` - -2. **Anthropic** - - `ANTHROPIC_API_KEY`: Authentication for Claude models - ```bash - ANTHROPIC_API_KEY="your-anthropic-key" - ``` - -3. **Google** - - `GEMINI_API_KEY`: Authentication for Gemini models - -4. **Hugging Face** - - `HUGGINGFACE_TOKEN`: Access to Hugging Face models - -5. **Perplexity AI** - - `PPLX_API_KEY`: Access to Perplexity models - -6. **AI21** - - `AI21_API_KEY`: Access to AI21 models - -#### Tool Provider Keys - -1. **Search Tools** - - `BING_BROWSER_API`: Bing search capabilities - - `BRAVESEARCH_API_KEY`: Brave search integration - - `TAVILY_API_KEY`: Tavily search services - - `YOU_API_KEY`: You.com search integration - -2. **Analytics & Monitoring** - - `EXA_API_KEY`: Exa.ai services - -3. **Browser Automation** - - `MULTION_API_KEY`: Multi-browser automation +=== "Configuration Variables" + + | Variable | Description | Example | + |----------|-------------|---------| + | `SWARMS_VERBOSE_GLOBAL` | Controls global logging verbosity | `True` or `False` | + | `WORKSPACE_DIR` | Defines the workspace directory for agent operations | `agent_workspace` | + +### LLM Provider API Keys + +=== "OpenAI" + ```bash + OPENAI_API_KEY="your-openai-key" + ``` + +=== "Anthropic" + ```bash + ANTHROPIC_API_KEY="your-anthropic-key" + ``` + +=== "Groq" + ```bash + GROQ_API_KEY="your-groq-key" + ``` + +=== "Google" + ```bash + GEMINI_API_KEY="your-gemini-key" + ``` + +=== "Hugging Face" + ```bash + HUGGINGFACE_TOKEN="your-huggingface-token" + ``` + +=== "Perplexity AI" + ```bash + PPLX_API_KEY="your-perplexity-key" + ``` + +=== "AI21" + ```bash + AI21_API_KEY="your-ai21-key" + ``` + +=== "Cohere" + ```bash + COHERE_API_KEY="your-cohere-key" + ``` + +=== "Mistral AI" + ```bash + MISTRAL_API_KEY="your-mistral-key" + ``` + +=== "Together AI" + ```bash + TOGETHER_API_KEY="your-together-key" + ``` + +### Tool Provider Keys + +=== "Search Tools" + ```bash + BING_BROWSER_API="your-bing-key" + BRAVESEARCH_API_KEY="your-brave-key" + TAVILY_API_KEY="your-tavily-key" + YOU_API_KEY="your-you-key" + ``` + +=== "Analytics & Monitoring" + ```bash + EXA_API_KEY="your-exa-key" + ``` + +=== "Browser Automation" + ```bash + MULTION_API_KEY="your-multion-key" + ``` - ## Security Best Practices -### 1. Environment File Management +### Environment File Management -- Create a `.env` file in your project root -- Never commit `.env` files to version control -- Add `.env` to your `.gitignore`: - ```bash - echo ".env" >> .gitignore - ``` +1. Create a `.env` file in your project root +2. Never commit `.env` files to version control +3. Add `.env` to your `.gitignore`: + ```bash + echo ".env" >> .gitignore + ``` -### 2. API Key Security +### API Key Security -- Rotate API keys regularly -- Use different API keys for development and production -- Never hardcode API keys in your code -- Limit API key permissions to only what's necessary -- Monitor API key usage for unusual patterns +!!! warning "Important Security Considerations" + - Rotate API keys regularly + - Use different API keys for development and production + - Never hardcode API keys in your code + - Limit API key permissions to only what's necessary + - Monitor API key usage for unusual patterns -### 3. Template Configuration +### Template Configuration Create a `.env.example` template without actual values: @@ -91,13 +115,14 @@ Create a `.env.example` template without actual values: # Required Configuration OPENAI_API_KEY="" ANTHROPIC_API_KEY="" +GROQ_API_KEY="" WORKSPACE_DIR="agent_workspace" # Optional Configuration SWARMS_VERBOSE_GLOBAL="False" ``` -### 4. Loading Environment Variables +### Loading Environment Variables ```python from dotenv import load_dotenv @@ -113,75 +138,65 @@ openai_key = os.getenv("OPENAI_API_KEY") ## Environment Setup Guide -1. **Install Dependencies**: - ```bash - pip install python-dotenv - ``` +=== "1. Install Dependencies" + ```bash + pip install python-dotenv + ``` -2. **Create Environment File**: - ```bash - cp .env.example .env - ``` +=== "2. Create Environment File" + ```bash + cp .env.example .env + ``` -3. **Configure Variables**: - - Open `.env` in your text editor - - Add your API keys and configuration - - Save the file +=== "3. Configure Variables" + - Open `.env` in your text editor + - Add your API keys and configuration + - Save the file -4. **Verify Setup**: - ```python - import os - from dotenv import load_dotenv +=== "4. Verify Setup" + ```python + import os + from dotenv import load_dotenv - load_dotenv() - assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" - ``` + load_dotenv() + assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found" + ``` ## Environment-Specific Configuration -### Development +=== "Development" + ```bash + WORKSPACE_DIR="agent_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` -```bash -WORKSPACE_DIR="agent_workspace" -SWARMS_VERBOSE_GLOBAL="True" -``` - -### Production - -```bash -WORKSPACE_DIR="/var/swarms/workspace" -SWARMS_VERBOSE_GLOBAL="False" -``` - -### Testing +=== "Production" + ```bash + WORKSPACE_DIR="/var/swarms/workspace" + SWARMS_VERBOSE_GLOBAL="False" + ``` -```bash -WORKSPACE_DIR="test_workspace" -SWARMS_VERBOSE_GLOBAL="True" -``` +=== "Testing" + ```bash + WORKSPACE_DIR="test_workspace" + SWARMS_VERBOSE_GLOBAL="True" + ``` ## Troubleshooting ### Common Issues -1. **Environment Variables Not Loading** - - Verify `.env` file exists in project root - - Confirm `load_dotenv()` is called before accessing variables - - Check file permissions - -2. **API Key Issues** - - Verify key format is correct - - Ensure key has not expired - - Check for leading/trailing whitespace - -3. **Workspace Directory Problems** - - Confirm directory exists - - Verify write permissions - - Check path is absolute when required - -## Additional Resources +???+ note "Environment Variables Not Loading" + - Verify `.env` file exists in project root + - Confirm `load_dotenv()` is called before accessing variables + - Check file permissions -- [Swarms Documentation](https://docs.swarms.world) -- [Security Best Practices](https://swarms.world/security) -- [API Documentation](https://swarms.world/docs/api) +???+ note "API Key Issues" + - Verify key format is correct + - Ensure key has not expired + - Check for leading/trailing whitespace +???+ note "Workspace Directory Problems" + - Confirm directory exists + - Verify write permissions + - Check path is absolute when required