Environment Variables

Overview

Automagik Tools uses environment variables for configuration. Set these in your shell, .env file, or deployment platform.

Never commit secrets! Add .env to your .gitignore and use environment-specific configuration for production.

Core Configuration

Server Configuration

AUTOMAGIK_TOOLS_HOST

string

default:"localhost"

The host address for the Automagik Tools server

AUTOMAGIK_TOOLS_HOST=0.0.0.0  # Listen on all interfaces

AUTOMAGIK_TOOLS_SSE_PORT

number

default:"8884"

Port for SSE (Server-Sent Events) transport mode

AUTOMAGIK_TOOLS_SSE_PORT=8884

AUTOMAGIK_TOOLS_HTTP_PORT

number

default:"8885"

Port for HTTP transport mode

AUTOMAGIK_TOOLS_HTTP_PORT=8885

MCP_TRANSPORT

string

default:"stdio"

Transport mode (automatically detected in most cases)

MCP_TRANSPORT=stdio  # Options: stdio, sse, http

AI Provider Configuration

OpenAI (Required for Genie)

OPENAI_API_KEY

string

required

OpenAI API key for intelligence features and Genie orchestrator

OPENAI_API_KEY=sk-your-key-here

Required for Genie tool. Genie uses OpenAI models for orchestration and memory management.

GENIE_MODEL

string

default:"gpt-4.1"

OpenAI model used by Genie

GENIE_MODEL=gpt-4.1
# Alternatives: gpt-4.1-mini, gpt-4o, gpt-3.5-turbo

AUTOMAGIK_TOOLS_OPENAI_MODEL

string

default:"gpt-4.1-mini"

OpenAI model for processing OpenAPI tool responses

AUTOMAGIK_TOOLS_OPENAI_MODEL=gpt-4.1-mini

Automagik Suite Integration

Core Configuration

AUTOMAGIK_API_KEY

string

API key for Automagik Suite (Spark, Hive, Forge, Omni)

AUTOMAGIK_API_KEY=your-api-key-here

AUTOMAGIK_BASE_URL

string

default:"http://localhost:8881"

Base URL for Automagik Suite API

AUTOMAGIK_BASE_URL=http://localhost:8881

AUTOMAGIK_TIMEOUT

number

default:"30"

Request timeout in seconds

AUTOMAGIK_TIMEOUT=30

AUTOMAGIK_ENABLE_MARKDOWN

boolean

default:"true"

Enable AI-powered markdown enhancement of responses

AUTOMAGIK_ENABLE_MARKDOWN=true
# Set to false for raw JSON responses (better for Genie integration)

AUTOMAGIK_OPENAPI_URL

string

OpenAPI specification URL for Automagik Suite

AUTOMAGIK_OPENAPI_URL=http://localhost:8881/api/v1/openapi.json

Genie Configuration

Core Settings

GENIE_MEMORY_DB

string

default:"genie_memory.db"

SQLite database path for Genie’s persistent memory

GENIE_MEMORY_DB=genie_memory.db

GENIE_STORAGE_DB

string

default:"genie_storage.db"

SQLite database path for Genie’s storage

GENIE_STORAGE_DB=genie_storage.db

GENIE_SESSION_ID

string

default:"global_genie_session"

Session identifier for Genie conversations

GENIE_SESSION_ID=global_genie_session

GENIE_HISTORY_RUNS

number

default:"3"

Number of conversation history runs to maintain

GENIE_HISTORY_RUNS=3

GENIE_SHOW_TOOL_CALLS

boolean

default:"true"

Show detailed tool call information in responses

GENIE_SHOW_TOOL_CALLS=true

MCP Server Configuration

GENIE_MCP_CONFIGS

json

JSON configuration for connecting Genie to MCP servers

GENIE_MCP_CONFIGS='{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
    "env": {}
  },
  "github": {
    "command": "uvx",
    "args": ["mcp-server-git"],
    "env": {"GITHUB_TOKEN": "your-token"}
  }
}'

See Transport Configuration for detailed MCP server setup examples.

Performance Settings

GENIE_MCP_CLEANUP_TIMEOUT

number

default:"2.0"

Timeout for MCP connection cleanup in seconds

GENIE_MCP_CLEANUP_TIMEOUT=2.0

GENIE_SSE_CLEANUP_DELAY

number

default:"0.2"

Delay before SSE cleanup in seconds

GENIE_SSE_CLEANUP_DELAY=0.2

GENIE_AGGRESSIVE_CLEANUP

boolean

default:"true"

Enable aggressive resource cleanup

GENIE_AGGRESSIVE_CLEANUP=true

Evolution API (WhatsApp)

EVOLUTION_API_KEY

string

Evolution API key for WhatsApp automation

EVOLUTION_API_KEY=your_evolution_api_key_here

EVOLUTION_API_BASE_URL

string

default:"https://api.evolution.com"

Evolution API base URL

EVOLUTION_API_BASE_URL=https://api.evolution.com

EVOLUTION_API_INSTANCE

string

WhatsApp instance name

EVOLUTION_API_INSTANCE=my_whatsapp_instance

EVOLUTION_API_FIXED_RECIPIENT

string

Fixed recipient phone number for security (removes number parameter from tools)

EVOLUTION_API_FIXED_RECIPIENT=+1234567890@s.whatsapp.net

Setting this restricts all messages to a single recipient. Useful for testing and security.

EVOLUTION_API_TIMEOUT

number

default:"30"

Request timeout in seconds

EVOLUTION_API_TIMEOUT=30

EVOLUTION_API_MAX_RETRIES

number

default:"3"

Maximum number of retry attempts

EVOLUTION_API_MAX_RETRIES=3

Gemini Assistant

GEMINI_API_KEY

string

Google Gemini API key

GEMINI_API_KEY=your_gemini_api_key_here

GEMINI_MODEL

string

default:"gemini-2.0-flash-exp"

Gemini model to use

GEMINI_MODEL=gemini-2.0-flash-exp
# Alternatives: gemini-pro, gemini-1.5-pro

GEMINI_SESSION_TIMEOUT

number

default:"3600"

Session timeout in seconds

GEMINI_SESSION_TIMEOUT=3600

GEMINI_MAX_TOKENS

number

default:"8192"

Maximum tokens per response

GEMINI_MAX_TOKENS=8192

GEMINI_TEMPERATURE

number

default:"0.2"

Response temperature (0.0 - 2.0)

GEMINI_TEMPERATURE=0.2

GEMINI_MAX_SESSIONS

number

default:"10"

Maximum concurrent sessions

GEMINI_MAX_SESSIONS=10

Automagik Hive

HIVE_API_BASE_URL

string

default:"http://localhost:8886"

Automagik Hive API base URL

HIVE_API_BASE_URL=http://localhost:8886

HIVE_API_KEY

string

Automagik Hive API key (only if authentication is required)

HIVE_API_KEY=your_hive_api_key_here

HIVE_TIMEOUT

number

default:"30"

Request timeout in seconds

HIVE_TIMEOUT=30

Logging and Debugging

LOG_LEVEL

string

default:"INFO"

Global logging level

LOG_LEVEL=DEBUG      # Detailed logs
LOG_LEVEL=INFO       # Normal logs (default)
LOG_LEVEL=WARNING    # Warnings only
LOG_LEVEL=ERROR      # Errors only
LOG_LEVEL=CRITICAL   # Critical errors only

LOG_FOLDER

string

default:"./logs"

Directory for log files

LOG_FOLDER=./logs

ENVIRONMENT

string

default:"development"

Environment mode

ENVIRONMENT=development
# Options: development, staging, production

Global Settings

AUTOMAGIK_TIMEZONE

string

default:"UTC"

Global timezone for timestamps

AUTOMAGIK_TIMEZONE=UTC
# Examples: America/New_York, Europe/London, Asia/Tokyo

AUTOMAGIK_ENCRYPTION_KEY

string

Base64-encoded encryption key for secure data

AUTOMAGIK_ENCRYPTION_KEY=eW91ci10ZXN0LWVuY3J5cHRpb24ta2V5LS0tLS0tLS0=

Generate a secure key using: openssl rand -base64 32

Using .env Files

Create a .env file in your project root:

.env

# =================================================================
# Core Configuration
# =================================================================
OPENAI_API_KEY=sk-your-key-here
AUTOMAGIK_TOOLS_HOST=localhost
AUTOMAGIK_TOOLS_SSE_PORT=8884
AUTOMAGIK_TOOLS_HTTP_PORT=8885

# =================================================================
# Automagik Suite Integration
# =================================================================
AUTOMAGIK_API_KEY=your-api-key-here
AUTOMAGIK_BASE_URL=http://localhost:8881
AUTOMAGIK_ENABLE_MARKDOWN=true

# =================================================================
# Genie Configuration
# =================================================================
GENIE_MODEL=gpt-4.1
GENIE_MEMORY_DB=genie_memory.db
GENIE_SESSION_ID=my_session

# Example: Connect Genie to filesystem and GitHub
GENIE_MCP_CONFIGS='{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  },
  "github": {
    "command": "uvx",
    "args": ["mcp-server-git"],
    "env": {"GITHUB_TOKEN": "ghp_your_token"}
  }
}'

# =================================================================
# WhatsApp Integration (Optional)
# =================================================================
EVOLUTION_API_KEY=your_evolution_api_key
EVOLUTION_API_BASE_URL=https://api.evolution.com
EVOLUTION_API_INSTANCE=my_whatsapp_instance

# =================================================================
# Logging
# =================================================================
LOG_LEVEL=INFO
LOG_FOLDER=./logs
ENVIRONMENT=development

Download the complete example: .env.example

Environment-Specific Configuration

Development
Production
Testing

.env.development

ENVIRONMENT=development
LOG_LEVEL=DEBUG

# Local services
AUTOMAGIK_BASE_URL=http://localhost:8881
AUTOMAGIK_TOOLS_HOST=localhost
AUTOMAGIK_TOOLS_SSE_PORT=8884

# Enable markdown for readable output
AUTOMAGIK_ENABLE_MARKDOWN=true

# Genie with local MCP servers
GENIE_SHOW_TOOL_CALLS=true
GENIE_MCP_CONFIGS='{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  }
}'

Verification

Check your configuration is working:

# List available tools
uvx automagik-tools list

# Test with stdio transport
uvx automagik-tools tool genie --transport stdio

# Test with SSE transport
uvx automagik-tools tool genie --transport sse --port 8000

Expected output:

✓ Loaded environment from .env
✓ OpenAI API key configured
✓ Starting Genie on stdio transport
✓ Genie ready with 2 MCP servers

Troubleshooting

Missing OPENAI_API_KEY error

Error: OPENAI_API_KEY environment variable is required for Genie

Solution: Set your OpenAI API key

export OPENAI_API_KEY=sk-your-key-here
# Or add to .env file

Port already in use

Error: Address already in use: 0.0.0.0:8884

Solution: Change the port

export AUTOMAGIK_TOOLS_SSE_PORT=8890
# Or use a different port in the command
uvx automagik-tools tool genie --port 8890

Genie MCP connection fails

Error: Failed to connect to MCP server 'filesystem'

Solution: Verify MCP server configuration

# Test the MCP server directly
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check GENIE_MCP_CONFIGS is valid JSON
echo $GENIE_MCP_CONFIGS | python -m json.tool

Automagik Suite connection fails

Error: Could not connect to Automagik Suite at http://localhost:8881

Solution: Verify Automagik services are running

# Check if Automagik is running
curl http://localhost:8881/health

# Update base URL if needed
export AUTOMAGIK_BASE_URL=http://your-host:8881

Security Best Practices

Never Commit Secrets

Add .env to .gitignore immediately

.gitignore

.env
.env.*
!.env.example
genie_memory.db
genie_storage.db
logs/

Use Secret Management

In production, use services like:

AWS Secrets Manager
HashiCorp Vault
Kubernetes Secrets
Docker Secrets
Cloud provider solutions

Rotate API Keys

Regularly rotate all API keys:

OpenAI API keys
Automagik API keys
Evolution API keys
GitHub tokens

Principle of Least Privilege

Grant minimal permissions:

Read-only API keys when possible
Scoped tokens
Time-limited credentials

Next Steps

Transport Configuration

Configure stdio, SSE, and HTTP transports

Authentication

Setup API keys and authentication

CLI Overview

Learn the command-line interface

Deployment

Deploy to production

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

Overview

Core Configuration

Server Configuration

AI Provider Configuration

OpenAI (Required for Genie)

Automagik Suite Integration

Core Configuration

Genie Configuration

Core Settings

MCP Server Configuration

Performance Settings

Evolution API (WhatsApp)

Gemini Assistant

Automagik Hive

Logging and Debugging

Global Settings

Using .env Files

Environment-Specific Configuration

Verification

Troubleshooting

Security Best Practices

Never Commit Secrets

Use Secret Management

Rotate API Keys

Principle of Least Privilege

Next Steps

Transport Configuration

Authentication

CLI Overview

Deployment

Phase 1: Get It Running

Phase 2: Reference

Phase 3: Real Examples

Phase 4: Deep Concepts

Troubleshooting

​Overview

​Core Configuration

​Server Configuration

​AI Provider Configuration

​OpenAI (Required for Genie)

​Automagik Suite Integration

​Core Configuration

​Genie Configuration

​Core Settings

​MCP Server Configuration

​Performance Settings

​Evolution API (WhatsApp)

​Gemini Assistant

​Automagik Hive

​Logging and Debugging

​Global Settings

​Using .env Files

​Environment-Specific Configuration

​Verification

​Troubleshooting

​Security Best Practices

Never Commit Secrets

Use Secret Management

Rotate API Keys

Principle of Least Privilege

​Next Steps

Transport Configuration

Authentication

CLI Overview

Deployment

Overview

Core Configuration

Server Configuration

AI Provider Configuration

OpenAI (Required for Genie)

Automagik Suite Integration

Core Configuration

Genie Configuration

Core Settings

MCP Server Configuration

Performance Settings

Evolution API (WhatsApp)

Gemini Assistant

Automagik Hive

Logging and Debugging

Global Settings

Using .env Files

Environment-Specific Configuration

Verification

Troubleshooting

Security Best Practices

Next Steps