Configuration Files

Learn how to configure Plexus using YAML configuration files for managing environment variables and settings. This provides a more organized and maintainable alternative to using .env files.

Configuration File Locations

Plexus looks for configuration files in the following locations, in order of precedence:

{project}/.plexus/config.yaml (project-specific, highest priority)
{project}/.plexus/config.yml
~/.plexus/config.yaml (user-wide configuration)
~/.plexus/config.yml (lowest priority)

💡 Recommendation

Use .plexus/config.yaml in your project directory for project-specific settings. This keeps your configuration version-controlled and consistent across team members.

Getting Started

The easiest way to get started is to copy the example configuration file:

# Create the .plexus directory
mkdir -p .plexus

# Copy the example configuration
cp plexus.yaml.example .plexus/config.yaml

# Edit the configuration with your settings
nano .plexus/config.yaml

Configuration Structure

The YAML configuration supports all Plexus environment variables organized in a hierarchical structure:

# Environment and Debug Settings
environment: development  # development, staging, production
debug: false

# Core Plexus Configuration
plexus:
  api_url: https://your-plexus-instance.appsync-api.amazonaws.com/graphql
  api_key: da2-your-api-key-here
  app_url: https://plexus.anth.us
  account_key: your-account-key
  enable_batching: true
  
  # Optional: Change working directory when loading config
  # working_directory: /path/to/your/project

# AWS Configuration
aws:
  access_key_id: AKIA-YOUR-ACCESS-KEY
  secret_access_key: your-secret-access-key
  region_name: us-west-2
  
  # Storage Buckets (Amplify-generated bucket names)
  storage:
    report_block_details_bucket: "amplify-your-app-reportblockdetails-bucket"
    datasets_bucket: "amplify-your-app-datasets-bucket"
    task_attachments_bucket: "amplify-your-app-taskattachments-bucket"

# Celery Task Queue Configuration
celery:
  queue_name: plexus-celery-development
  result_backend_template: "dynamodb://{aws_access_key}:{aws_secret_key}@{aws_region_name}/plexus-action-development"

# AI/ML Service APIs
openai:
  api_key: sk-your-openai-api-key

anthropic:
  api_key: sk-ant-api03-your-anthropic-api-key

# Azure OpenAI Configuration
azure:
  api_key: your-azure-openai-key
  api_base: https://your-instance.openai.azure.com
  api_version: "2024-02-01"

# LangChain/LangSmith Configuration
langchain:
  api_key: lsv2_pt_your-langsmith-api-key
  endpoint: https://api.smith.langchain.com
  project: your-project-name
  tracing_v2: true

How Configuration Loading Works

Precedence Order

Configuration is loaded with the following precedence (highest to lowest priority):

Environment variables - Always take highest priority
Project-level config - .plexus/config.yaml in current directory
User-level config - ~/.plexus/config.yaml in home directory

Automatic Loading

Configuration is automatically loaded when you use:

Plexus CLI commands (e.g., plexus item last)
Plexus MCP server
Python code that imports Plexus modules

Configuration Logging

When configuration is loaded, you'll see a log message like:

Loaded Plexus configuration from 1 file(s): /project/.plexus/config.yaml - Set 34 environment variables

Special Features

Working Directory Change

You can specify a working directory in your configuration that will be set when the config loads:

plexus:
  working_directory: /path/to/your/project

Template Variables

Some configuration values support template variables. For example, the Celery result backend can reference AWS credentials:

celery:
  result_backend_template: "dynamodb://{aws_access_key}:{aws_secret_key}@{aws_region_name}/table-name"

Migration from .env Files

If you're currently using .env files, you can migrate to YAML configuration:

Step 1: Convert Variables

Transform your flat environment variables into the nested YAML structure:

Before (.env)

PLEXUS_API_URL=https://api.example.com
PLEXUS_API_KEY=da2-key
AWS_ACCESS_KEY_ID=AKIA123
AWS_SECRET_ACCESS_KEY=secret
OPENAI_API_KEY=sk-key

After (config.yaml)

plexus:
  api_url: https://api.example.com
  api_key: da2-key
aws:
  access_key_id: AKIA123
  secret_access_key: secret
openai:
  api_key: sk-key

Step 2: Test the Migration

Test that your configuration works by running a simple command:

plexus item last

Step 3: Remove .env File (Optional)

Once you've verified the YAML configuration works, you can remove your .env file.

Security Best Practices

⚠️ Security Notice

Never commit configuration files with real credentials to version control
Use .gitignore to exclude .plexus/config.yaml from git
Consider using separate config files for different environments
Use environment variables for the most sensitive credentials in production

Troubleshooting

Configuration Not Loading

If your configuration isn't being loaded:

Check the file path and ensure it's in one of the expected locations
Verify the YAML syntax is valid
Look for configuration loading log messages
Ensure the file has proper read permissions

Missing Environment Variables

If you get "missing environment variables" errors:

Check that the YAML structure matches the expected format
Verify that required fields like aws.access_key_id are present
Make sure there are no typos in the configuration keys

YAML Syntax Errors

Common YAML syntax issues:

Ensure proper indentation (use spaces, not tabs)
Quote strings that contain special characters
Use consistent spacing around colons
Validate your YAML using an online YAML validator

✅ Next Steps

Once you have your configuration file set up, try running plexus item last to verify everything is working correctly. You can also explore the Concepts section to learn more about how Plexus works.