> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugged.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Guide

> Configure Plugged.in for your specific needs

# Configuration Guide

<Info>
  **Using Plugged.in Cloud?** If you're using the hosted version at [plugged.in](https://plugged.in), configuration is already handled for you! Simply sign up and start using the platform. This guide is for self-hosted installations only.
</Info>

## Cloud vs Self-Hosted

<Tabs>
  <Tab title="Cloud (Recommended)">
    **No configuration needed!**

    The cloud version at [plugged.in](https://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

    [Sign up now →](https://plugged.in/register)
  </Tab>

  <Tab title="Self-Hosted">
    **Full control over your instance**

    Self-hosting gives you:

    * Complete data ownership
    * Custom domain and branding
    * Private network deployment
    * Specific compliance requirements
    * Custom integrations

    Continue reading for configuration instructions.
  </Tab>
</Tabs>

## 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

<Steps>
  <Step title="Create Database">
    ```bash theme={null}
    createdb pluggedin
    ```
  </Step>

  <Step title="Run Migrations">
    ```bash theme={null}
    cd pluggedin-app
    pnpm db:generate  # Generate Drizzle schema
    pnpm db:migrate   # Run database migrations
    ```
  </Step>

  <Step title="Verify Connection">
    Test your database connection:

    ```bash theme={null}
    psql $DATABASE_URL -c "SELECT version();"
    ```
  </Step>
</Steps>

<Note>
  For production environments, always use SSL connections:

  ```env theme={null}
  DATABASE_SSL=true
  DATABASE_SSL_REJECT_UNAUTHORIZED=true
  ```
</Note>

### 2. Authentication Setup

#### Generate Secret Keys

Generate all required secret keys for secure operation:

```bash theme={null}
# 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)"
```

<Warning>
  **Important**: Each key must be unique. Never reuse the same key for different purposes.
</Warning>

#### Configure OAuth Providers

<Tabs>
  <Tab title="GitHub">
    1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
    2. Create a new OAuth App
    3. Set Authorization callback URL: `http://localhost:12005/api/auth/callback/github`
    4. Add to `.env`:

    ```env theme={null}
    GITHUB_ID=your_client_id
    GITHUB_SECRET=your_client_secret
    GITHUB_TOKEN=your_personal_access_token  # For API calls
    ```
  </Tab>

  <Tab title="Google">
    1. Go to [Google Cloud Console](https://console.cloud.google.com)
    2. Create OAuth 2.0 credentials
    3. Add authorized redirect URI: `http://localhost:12005/api/auth/callback/google`
    4. Add to `.env`:

    ```env theme={null}
    GOOGLE_CLIENT_ID=your_client_id
    GOOGLE_CLIENT_SECRET=your_client_secret
    ```
  </Tab>
</Tabs>

### 3. MCP Proxy Configuration

Configure the MCP proxy server connection:

```env theme={null}
# 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:

```env theme={null}
# 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

<AccordionGroup>
  <Accordion title="SMTP Settings">
    ```env theme={null}
    # Email Server
    EMAIL_SERVER_HOST=smtp.gmail.com
    EMAIL_SERVER_PORT=587
    EMAIL_SERVER_USER=your-email@gmail.com
    EMAIL_SERVER_PASSWORD=your-app-password

    # Email Addresses
    EMAIL_FROM=noreply@plugged.in
    EMAIL_FROM_NAME=Plugged.in
    EMAIL_REPLY_TO=support@plugged.in
    ```
  </Accordion>

  <Accordion title="Email Automation">
    ```env theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Admin Notifications">
    ```env theme={null}
    # Admin Email Settings
    ADMIN_NOTIFICATION_EMAILS=admin@example.com,team@example.com
    ADMIN_NOTIFICATION_SEVERITIES=ALERT,CRITICAL
    ADMIN_DAILY_SUMMARY=false
    ADMIN_FAILED_LOGIN_THRESHOLD=5
    ```
  </Accordion>
</AccordionGroup>

### 5. Feature Flags

Enable or disable specific features:

```env theme={null}
# 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:

<CodeGroup>
  ```env Anthropic theme={null}
  ANTHROPIC_API_KEY=sk-ant-api03-...
  ```

  ```env OpenAI theme={null}
  OPENAI_API_KEY=sk-...
  ```

  ```env Google theme={null}
  GOOGLE_API_KEY=AIza...
  ```
</CodeGroup>

### 7. Production Configuration

#### SSL/TLS Setup

For production, configure proper SSL:

```env theme={null}
# 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):

```nginx theme={null}
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:

```env theme={null}
# 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

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Linux">
    Edit `~/.config/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

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

```json theme={null}
{
  "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:

```env theme={null}
# 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:

```env theme={null}
# 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:

```env theme={null}
NEXT_PUBLIC_ADMIN_USERS=admin@example.com,team@example.com
ADMIN_MIGRATION_SECRET=$(openssl rand -base64 32)
```

## Validation Checklist

After configuration, verify your setup:

<Steps>
  <Step title="Test Database">
    ```bash theme={null}
    pnpm db:migrate
    ```
  </Step>

  <Step title="Verify Auth">
    Start the app and try logging in:

    ```bash theme={null}
    pnpm dev
    ```
  </Step>

  <Step title="Check MCP Connection">
    ```bash theme={null}
    curl http://localhost:3000/health
    ```
  </Step>

  <Step title="Test Email (if configured)">
    Send a test email through the admin panel
  </Step>
</Steps>

## 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](/quickstart/installation#3-configure-environment-variables).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database Connection Issues">
    * Verify PostgreSQL is running: `pg_isready`
    * Check connection string format
    * Ensure database exists: `psql -l`
    * Verify user permissions
  </Accordion>

  <Accordion title="Authentication Problems">
    * Regenerate NEXTAUTH\_SECRET
    * Clear browser cookies
    * Verify callback URLs match OAuth provider settings
    * Check NEXTAUTH\_URL matches your domain
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Email Not Sending">
    * Verify SMTP credentials
    * Check app-specific passwords (Gmail)
    * Test connection with telnet/openssl
    * Review email server logs
  </Accordion>
</AccordionGroup>

## Next Steps

* [Add MCP Servers](/platform/registry)
* [Configure Security Settings](/security/overview)
* [Set Up Deployment](/deployment/ubuntu-setup)
* [API Integration](/api/reference)