Configuration Guide

Using Plugged.in Cloud? If you’re using the hosted version at plugged.in, configuration is already handled for you! Simply sign up and start using the platform. This guide is for self-hosted installations only.

Cloud vs Self-Hosted

Cloud (Recommended)
Self-Hosted

No configuration needed!The cloud version at plugged.in provides:

✅ Automatic updates and maintenance
✅ Pre-configured security and optimization
✅ Managed database and backups
✅ OAuth providers already set up
✅ Email delivery configured
✅ SSL/TLS certificates included

Self-Hosted Configuration

This guide covers the essential configuration steps after installing Plugged.in self-hosted, including database setup, authentication, features, and optimization settings.

Initial Setup

After installation, follow these steps to configure your Plugged.in instance properly.

1. Database Configuration

Create Database

createdb pluggedin

Run Migrations

cd pluggedin-app
pnpm db:generate  # Generate Drizzle schema
pnpm db:migrate   # Run database migrations

Verify Connection

Test your database connection:

psql $DATABASE_URL -c "SELECT version();"

For production environments, always use SSL connections:

DATABASE_SSL=true
DATABASE_SSL_REJECT_UNAUTHORIZED=true

2. Authentication Setup

Generate Secret Keys

Generate all required secret keys for secure operation:

# Generate and save these to your .env file
echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)"
echo "NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=$(openssl rand -base64 32)"
echo "UNSUBSCRIBE_TOKEN_SECRET=$(openssl rand -base64 32)"

Important: Each key must be unique. Never reuse the same key for different purposes.

Configure OAuth Providers

GitHub
Google

Go to GitHub Developer Settings
Create a new OAuth App
Set Authorization callback URL: http://localhost:12005/api/auth/callback/github
Add to .env:

GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret
GITHUB_TOKEN=your_personal_access_token  # For API calls

Go to Google Cloud Console
Create OAuth 2.0 credentials
Add authorized redirect URI: http://localhost:12005/api/auth/callback/google
Add to .env:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

3. MCP Proxy Configuration

Configure the MCP proxy server connection:

# Registry Configuration
REGISTRY_API_URL=http://localhost:3001
REGISTRY_INTERNAL_API_KEY=$(openssl rand -base64 32)

# MCP Proxy Settings
PLUGGEDIN_API_KEY=$(openssl rand -base64 32)
PLUGGEDIN_MCP_URL=http://localhost:3000

MCP Resource Limits

Control resource usage for MCP servers:

# CPU and Memory Limits
MCP_CPU_CORES_MAX=0.5              # 50% of one core
MCP_MEMORY_MAX_MB=512              # Maximum memory per server

# I/O Limits
MCP_IO_READ_MBPS=10                # Max read speed
MCP_IO_WRITE_MBPS=5                # Max write speed

# Timeout Settings
MCP_PROCESS_TIMEOUT_MS=300000      # 5 minutes max runtime
MCP_STARTUP_TIMEOUT_MS=10000       # 10 seconds to start

4. Email Configuration

SMTP Settings

# Email Server
EMAIL_SERVER_HOST=smtp.gmail.com
EMAIL_SERVER_PORT=587
[email protected]
EMAIL_SERVER_PASSWORD=your-app-password

# Email Addresses
[email protected]
EMAIL_FROM_NAME=Plugged.in
[email protected]

Email Automation

# Welcome Emails
ENABLE_WELCOME_EMAILS=true
WELCOME_EMAIL_DELAY_MINUTES=5

# Follow-up Emails
ENABLE_FOLLOW_UP_EMAILS=true
FOLLOW_UP_2_DAYS=2
FOLLOW_UP_5_DAYS=5

# Email Verification
ENABLE_EMAIL_VERIFICATION=false

Admin Notifications

# Admin Email Settings
[email protected],[email protected]
ADMIN_NOTIFICATION_SEVERITIES=ALERT,CRITICAL
ADMIN_DAILY_SUMMARY=false
ADMIN_FAILED_LOGIN_THRESHOLD=5

5. Feature Flags

Enable or disable specific features:

# Core Features
ENABLE_RAG=true                    # Document processing
ENABLE_NOTIFICATIONS=true          # Notification system

# Security Features
ENABLE_EMAIL_VERIFICATION=false    # Require email verification

6. AI Model Configuration

Configure API keys for AI model providers:

ANTHROPIC_API_KEY=sk-ant-api03-...

7. Production Configuration

SSL/TLS Setup

For production, configure proper SSL:

# Production URLs
NEXTAUTH_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Database SSL
DATABASE_SSL=true
DATABASE_SSL_REJECT_UNAUTHORIZED=true

Security Headers

Add security headers in your reverse proxy (nginx example):

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

Rate Limiting

Configure rate limiting for production:

# Rate Limit Configuration
RATE_LIMIT_SERVER_MOD_WINDOW_MS=60000    # 1 minute window
RATE_LIMIT_SERVER_MOD_MAX=10             # Max modifications
RATE_LIMIT_SENSITIVE_WINDOW_MS=3600000   # 1 hour window
RATE_LIMIT_SENSITIVE_MAX=10              # Max sensitive ops

MCP Client Configuration

Claude Desktop Configuration

macOS
Windows
Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pluggedin": {
      "command": "node",
      "args": ["/path/to/pluggedin-mcp/dist/index.js"],
      "env": {
        "PLUGGEDIN_API_KEY": "your-api-key",
        "PLUGGEDIN_BASE_URL": "https://your-domain.com"
      }
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "pluggedin": {
      "command": "node",
      "args": ["C:\\path\\to\\pluggedin-mcp\\dist\\index.js"],
      "env": {
        "PLUGGEDIN_API_KEY": "your-api-key",
        "PLUGGEDIN_BASE_URL": "https://your-domain.com"
      }
    }
  }
}

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pluggedin": {
      "command": "node",
      "args": ["/home/user/pluggedin-mcp/dist/index.js"],
      "env": {
        "PLUGGEDIN_API_KEY": "your-api-key",
        "PLUGGEDIN_BASE_URL": "https://your-domain.com"
      }
    }
  }
}

Other MCP Clients

For Cursor, Cline, or other MCP clients, the configuration pattern is similar:

{
  "command": "node",
  "args": ["path/to/pluggedin-mcp/dist/index.js"],
  "env": {
    "PLUGGEDIN_API_KEY": "your-api-key"
  }
}

Advanced Configuration

Package Management

Configure package storage and caching:

# Package Storage
MCP_PACKAGE_STORE_DIR=/var/mcp-packages
MCP_PNPM_STORE_DIR=/var/mcp-packages/pnpm-store
MCP_UV_CACHE_DIR=/var/mcp-packages/uv-cache

# Cache Settings
MCP_PACKAGE_CACHE_DAYS=30
MCP_PREWARM_COMMON_PACKAGES=true

Isolation Configuration

Configure security isolation for MCP servers:

# Isolation Type
MCP_ISOLATION_TYPE=bubblewrap      # Options: bubblewrap, firejail, none
MCP_ISOLATION_FALLBACK=firejail    # Fallback if primary unavailable
MCP_ENABLE_NETWORK_ISOLATION=false # Per-server network namespaces

Custom Admin Users

Define admin users for special privileges:

[email protected],[email protected]
ADMIN_MIGRATION_SECRET=$(openssl rand -base64 32)

Validation Checklist

After configuration, verify your setup:

Test Database

pnpm db:migrate

Verify Auth

Start the app and try logging in:

pnpm dev

Check MCP Connection

curl http://localhost:3000/health

Test Email (if configured)

Send a test email through the admin panel

Environment Variables Reference

For a complete list of all environment variables, see the .env.example file in the repository or refer to the Installation Guide.

Troubleshooting

Database Connection Issues

Verify PostgreSQL is running: pg_isready
Check connection string format
Ensure database exists: psql -l
Verify user permissions

Authentication Problems

Regenerate NEXTAUTH_SECRET
Clear browser cookies
Verify callback URLs match OAuth provider settings
Check NEXTAUTH_URL matches your domain

MCP Proxy Not Connecting

Verify API keys match between app and proxy
Check proxy is running: curl http://localhost:3000/health
Review proxy logs for errors
Ensure ports are not blocked by firewall

Email Not Sending

Verify SMTP credentials
Check app-specific passwords (Gmail)
Test connection with telnet/openssl
Review email server logs

Getting Started

Platform Features

PAP Agents

Tutorials

Security

Deployment

Observability

Testing

Migration Guides

Troubleshooting

Advanced Configuration

Integration Guides

Performance

​Configuration Guide

​Cloud vs Self-Hosted

​Self-Hosted Configuration

​Initial Setup

​1. Database Configuration

​2. Authentication Setup

​Generate Secret Keys

​Configure OAuth Providers

​3. MCP Proxy Configuration

​MCP Resource Limits

​4. Email Configuration

​5. Feature Flags

​6. AI Model Configuration

​7. Production Configuration

​SSL/TLS Setup

​Security Headers

​Rate Limiting

​MCP Client Configuration

​Claude Desktop Configuration

​Other MCP Clients

​Advanced Configuration

​Package Management

​Isolation Configuration

​Custom Admin Users

​Validation Checklist

​Environment Variables Reference

​Troubleshooting

​Next Steps

Configuration Guide

Cloud vs Self-Hosted

Self-Hosted Configuration

Initial Setup

1. Database Configuration

2. Authentication Setup

Generate Secret Keys

Configure OAuth Providers

3. MCP Proxy Configuration

MCP Resource Limits

4. Email Configuration

5. Feature Flags

6. AI Model Configuration

7. Production Configuration

SSL/TLS Setup

Security Headers

Rate Limiting

MCP Client Configuration

Claude Desktop Configuration

Other MCP Clients

Advanced Configuration

Package Management

Isolation Configuration

Custom Admin Users

Validation Checklist

Environment Variables Reference

Troubleshooting

Next Steps