Environment Setup

Overview

Before you can start using Swarms, you need to configure your environment with the necessary API keys and settings. This guide will walk you through setting up your environment variables and workspace directory.

Swarms supports multiple LLM providers including OpenAI, Anthropic, Groq, and more. You only need to configure the API keys for the providers you plan to use.

Quick Setup

The fastest way to get started is to create a .env file in your project root:

Create a .env file

Create a file named .env in your project’s root directory:

touch .env

Add your API keys

Add your API keys to the .env file:

OPENAI_API_KEY="your-openai-api-key-here"
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY="your-anthropic-api-key-here"
GROQ_API_KEY="your-groq-api-key-here"

Verify the setup

Load and verify your environment variables:

import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Verify API keys are loaded
print(f"OpenAI API Key: {os.getenv('OPENAI_API_KEY')[:10]}...")
print(f"Workspace: {os.getenv('WORKSPACE_DIR')}")

Required Environment Variables

Core Configuration

string

default:"agent_workspace"

The directory where agents will store their outputs, logs, and temporary files.

WORKSPACE_DIR="agent_workspace"

LLM Provider API Keys

Configure the API keys for the LLM providers you want to use:

string

required

Your OpenAI API key for using GPT models (gpt-4, gpt-4o-mini, etc.)Get your key: OpenAI API Keys

OPENAI_API_KEY="sk-..."

string

Your Anthropic API key for using Claude models (claude-sonnet-4-5, etc.)Get your key: Anthropic Console

ANTHROPIC_API_KEY="sk-ant-..."

string

Your Groq API key for using Groq’s fast LLM inferenceGet your key: Groq Console

GROQ_API_KEY="gsk_..."

Complete .env File Example

Here’s a complete example of a .env file with all supported providers:

.env

# Core Configuration
WORKSPACE_DIR="agent_workspace"

# OpenAI
OPENAI_API_KEY="sk-proj-..."

# Anthropic
ANTHROPIC_API_KEY="sk-ant-..."

# Groq
GROQ_API_KEY="gsk_..."

# Additional Providers (Optional)
COHERE_API_KEY="your-cohere-key"
DEEPSEEK_API_KEY="your-deepseek-key"
OPENROUTER_API_KEY="your-openrouter-key"
XAI_API_KEY="your-xai-key"

# Workspace Settings (Optional)
LOG_LEVEL="INFO"
MAX_WORKERS="4"
CACHE_ENABLED="true"

Security Best Practices:

Never commit your .env file to version control
Add .env to your .gitignore file
Use different API keys for development and production
Rotate your API keys regularly

Workspace Directory Setup

The workspace directory is where agents store their outputs, logs, and state:

Default Structure

agent_workspace/
├── logs/              # Agent execution logs
├── outputs/           # Agent-generated outputs
├── cache/             # Cached results
└── state/             # Agent state files

Custom Workspace Configuration

You can customize the workspace location:

import os
from swarms import Agent

# Set workspace directory
os.environ["WORKSPACE_DIR"] = "/path/to/custom/workspace"

# Or specify per-agent
agent = Agent(
    model_name="gpt-5.4",
    workspace_dir="./my_agent_workspace"
)

Use absolute paths for workspace directories in production environments to avoid path resolution issues.

Loading Environment Variables

There are several ways to load your environment variables:

Method 1: Using python-dotenv (Recommended)

from dotenv import load_dotenv
import os

# Load from .env file
load_dotenv()

# Access variables
api_key = os.getenv("OPENAI_API_KEY")
workspace = os.getenv("WORKSPACE_DIR", "agent_workspace")  # with default

Method 2: Manual Loading

import os

# Set environment variables directly
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["WORKSPACE_DIR"] = "agent_workspace"

Method 3: System Environment Variables

Linux/macOS
Windows (PowerShell)
Windows (CMD)

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY="your-api-key"
export WORKSPACE_DIR="agent_workspace"

# Reload shell configuration
source ~/.bashrc

# Set for current session
$env:OPENAI_API_KEY = "your-api-key"
$env:WORKSPACE_DIR = "agent_workspace"

# Set permanently
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'your-api-key', 'User')

# Set for current session
set OPENAI_API_KEY=your-api-key
set WORKSPACE_DIR=agent_workspace

# Set permanently
setx OPENAI_API_KEY "your-api-key"

Getting API Keys

Here’s where to get API keys for each supported provider:

OpenAI

Create an account and generate API keys from the OpenAI platform

Anthropic

Groq

Cohere

Create a Cohere account and access your API keys

DeepSeek

OpenRouter

Access multiple models through OpenRouter with a single API key

Verifying Your Setup

Run this script to verify your environment is configured correctly:

verify_setup.py

import os
from dotenv import load_dotenv
from swarms import Agent

# Load environment variables
load_dotenv()

def verify_setup():
    """Verify that the environment is properly configured."""
    
    print("🔍 Verifying Swarms Environment Setup...\n")
    
    # Check workspace directory
    workspace = os.getenv("WORKSPACE_DIR", "agent_workspace")
    print(f"✓ Workspace Directory: {workspace}")
    
    # Check API keys
    providers = {
        "OpenAI": "OPENAI_API_KEY",
        "Anthropic": "ANTHROPIC_API_KEY",
        "Groq": "GROQ_API_KEY",
    }
    
    configured_providers = []
    for name, env_var in providers.items():
        if os.getenv(env_var):
            configured_providers.append(name)
            print(f"✓ {name} API Key: Configured")
        else:
            print(f"✗ {name} API Key: Not configured")
    
    print(f"\n✨ Setup complete! {len(configured_providers)} provider(s) configured.")
    
    # Test agent creation
    if "OpenAI" in configured_providers:
        print("\n🤖 Testing agent creation...")
        try:
            agent = Agent(
                model_name="gpt-5.4",
                max_loops=1,
            )
            response = agent.run("Say 'Setup verified!'")
            print(f"✓ Agent test successful: {response[:50]}...")
        except Exception as e:
            print(f"✗ Agent test failed: {str(e)}")

if __name__ == "__main__":
    verify_setup()

Run the verification script:

python verify_setup.py

Environment Best Practices

Use different environments for dev/prod

Create separate .env files for different environments:

.env.development
.env.production
.env.test

Load the appropriate one:

from dotenv import load_dotenv
import os

env = os.getenv("ENV", "development")
load_dotenv(f".env.{env}")

Validate required variables

Always validate that required environment variables are set:

import os

required_vars = ["OPENAI_API_KEY", "WORKSPACE_DIR"]
missing_vars = [var for var in required_vars if not os.getenv(var)]

if missing_vars:
    raise EnvironmentError(
        f"Missing required environment variables: {', '.join(missing_vars)}"
    )

Use secret management in production

For production deployments, use proper secret management:

AWS: AWS Secrets Manager or Parameter Store
Azure: Azure Key Vault
GCP: Google Secret Manager
Kubernetes: Kubernetes Secrets
Docker: Docker Secrets

Rotate API keys regularly

Set up a key rotation schedule (e.g., every 90 days)
Monitor API key usage for anomalies
Use separate keys for different applications
Revoke unused or compromised keys immediately

Troubleshooting

Environment variables not loading

Verify the .env file is in the correct directory
Check that you’re calling load_dotenv() before accessing variables
Ensure there are no syntax errors in the .env file
Try printing os.getcwd() to verify current directory

API key authentication errors

Verify the API key is correct (no extra spaces or quotes)
Check that the key has the necessary permissions
Ensure the key hasn’t expired or been revoked
Test the key directly with the provider’s API

Workspace directory errors

Ensure the directory path exists or can be created
Check file system permissions
Use absolute paths to avoid resolution issues
Verify sufficient disk space

Next Steps

Quickstart Guide

Create your first agent now that your environment is configured

Model Providers

Learn about all supported LLM providers and how to use them

For more detailed information about environment configuration, visit the official documentation.

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Environment Setup

Overview

Quick Setup

Required Environment Variables

Core Configuration

LLM Provider API Keys

Complete .env File Example

Workspace Directory Setup

Default Structure

Custom Workspace Configuration

Loading Environment Variables

Method 1: Using python-dotenv (Recommended)

Method 2: Manual Loading

Method 3: System Environment Variables

Getting API Keys

OpenAI

Anthropic

Groq

Cohere

DeepSeek

OpenRouter

Verifying Your Setup

Environment Best Practices

Troubleshooting

Next Steps

Quickstart Guide

Model Providers

​Overview

​Quick Setup

​Required Environment Variables

​Core Configuration

​LLM Provider API Keys

​Complete .env File Example

​Workspace Directory Setup

​Default Structure

​Custom Workspace Configuration

​Loading Environment Variables

​Method 1: Using python-dotenv (Recommended)

​Method 2: Manual Loading

​Method 3: System Environment Variables

​Getting API Keys

OpenAI

Anthropic

Groq

Cohere

DeepSeek

OpenRouter

​Verifying Your Setup

​Environment Best Practices

​Troubleshooting

​Next Steps

Quickstart Guide

Model Providers

Overview

Quick Setup

Required Environment Variables

Core Configuration

LLM Provider API Keys

Complete .env File Example

Workspace Directory Setup

Default Structure

Custom Workspace Configuration

Loading Environment Variables

Method 1: Using python-dotenv (Recommended)

Method 2: Manual Loading

Method 3: System Environment Variables

Getting API Keys

Verifying Your Setup

Environment Best Practices

Troubleshooting

Next Steps