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

# Installation Guide

> Get started with Plugged.in in minutes

# Installation Guide

Get up and running with Plugged.in quickly. Choose between using our hosted platform or self-hosting the application.

<Note>
  **🚀 Recommended**: Use [Plugged.in Cloud](https://plugged.in) for the fastest setup with zero configuration. The cloud version is fully managed, always up-to-date, and includes all features out of the box.
</Note>

## Quick Start (Cloud Platform - Recommended)

The fastest way to get started is using our hosted platform at [plugged.in](https://plugged.in). No installation required!

<Steps>
  <Step title="Sign Up">
    Create your account at [plugged.in/register](https://plugged.in/register)
  </Step>

  <Step title="Configure MCP Proxy">
    Install the MCP proxy following the instructions in your dashboard
  </Step>

  <Step title="Add MCP Servers">
    Browse and add servers from the registry or configure your own
  </Step>

  <Step title="Connect Your Client">
    Use the generated configuration with Claude, Cursor, or other MCP clients
  </Step>
</Steps>

## Self-Hosting

For organizations that prefer to host their own instance, follow these comprehensive steps.

### Prerequisites

<CardGroup cols={2}>
  <Card title="System Requirements" icon="server">
    * Node.js 18+ or 20+
    * PostgreSQL 15+ (18+ recommended)
    * 2GB+ RAM
    * 10GB+ storage
  </Card>

  <Card title="Optional Services" icon="plug">
    * Redis (for caching)
    * SMTP server (for emails)
    * S3-compatible storage
  </Card>
</CardGroup>

### Installation Steps

#### 1. Clone the Repositories

<CodeGroup>
  ```bash Web Application theme={null}
  git clone https://github.com/VeriTeknik/pluggedin-app.git
  cd pluggedin-app
  ```

  ```bash MCP Proxy theme={null}
  git clone https://github.com/VeriTeknik/pluggedin-mcp.git
  cd pluggedin-mcp
  ```
</CodeGroup>

#### 2. Install Dependencies

<Tabs>
  <Tab title="pnpm (recommended)">
    ```bash theme={null}
    # Web application
    cd pluggedin-app
    pnpm install

    # MCP Proxy
    cd ../pluggedin-mcp
    npm install
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    # Web application
    cd pluggedin-app
    npm install

    # MCP Proxy
    cd ../pluggedin-mcp
    npm install
    ```
  </Tab>
</Tabs>

#### 3. Configure Environment Variables

Create a `.env` file in the `pluggedin-app` directory based on `.env.example`:

<Tabs>
  <Tab title="Required Configuration">
    ```bash theme={null}
    # Database
    DATABASE_URL="postgresql://user:password@localhost:5432/pluggedin"
    DATABASE_SSL=false                     # Set to true for production
    DATABASE_SSL_REJECT_UNAUTHORIZED=false # Set to false for self-signed certs

    # Authentication
    NEXTAUTH_URL="http://localhost:12005"
    NEXTAUTH_SECRET="your-secret-key-here" # Generate with: openssl rand -base64 32
    NEXT_PUBLIC_APP_URL="http://localhost:12005"

    # Encryption (REQUIRED for MCP server configs)
    NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="" # Generate with: openssl rand -base64 32

    # Feature Flags
    ENABLE_RAG=true                    # Enable document processing
    ENABLE_NOTIFICATIONS=true          # Enable notification system
    ENABLE_EMAIL_VERIFICATION=false    # Email verification for new users
    ```
  </Tab>

  <Tab title="Email Configuration">
    ```bash theme={null}
    # Email Server (Optional but recommended)
    EMAIL_FROM="noreply@plugged.in"
    EMAIL_FROM_NAME="Pluggedin"
    EMAIL_REPLY_TO="support@plugged.in"
    EMAIL_SERVER_HOST="smtp.example.com"
    EMAIL_SERVER_PORT="587"
    EMAIL_SERVER_USER=""
    EMAIL_SERVER_PASSWORD=""

    # Email Automation
    ENABLE_WELCOME_EMAILS=true
    ENABLE_FOLLOW_UP_EMAILS=true
    WELCOME_EMAIL_DELAY_MINUTES=5
    FOLLOW_UP_2_DAYS=2
    FOLLOW_UP_5_DAYS=5

    # Unsubscribe Security
    UNSUBSCRIBE_TOKEN_SECRET="" # Generate with: openssl rand -base64 32
    ```
  </Tab>

  <Tab title="OAuth Providers">
    ```bash theme={null}
    # GitHub OAuth (for registry features)
    GITHUB_ID=""
    GITHUB_SECRET=""
    GITHUB_TOKEN=""            # For API calls
    GITHUB_CLIENT_ID=""        # For registry auth

    # Google OAuth
    GOOGLE_CLIENT_ID=""
    GOOGLE_CLIENT_SECRET=""

    # Twitter OAuth
    TWITTER_CLIENT_ID=""
    TWITTER_CLIENT_SECRET=""
    ```
  </Tab>

  <Tab title="AI & Registry">
    ```bash theme={null}
    # AI Model API Keys (Optional)
    ANTHROPIC_API_KEY=""
    OPENAI_API_KEY=""
    GOOGLE_API_KEY=""

    # Registry Configuration
    REGISTRY_API_URL="http://localhost:3001"
    REGISTRY_INTERNAL_API_KEY="your-secure-internal-api-key"
    REGISTRY_AUTH_TOKEN=""     # JWT for publishing

    # RAG Configuration
    RAG_API_URL=""
    ```
  </Tab>

  <Tab title="Advanced Settings">
    ```bash theme={null}
    # Admin Configuration
    ADMIN_NOTIFICATION_EMAILS=""           # Comma-separated admin emails
    ADMIN_NOTIFICATION_SEVERITIES="ALERT,CRITICAL"
    ADMIN_DAILY_SUMMARY=false
    ADMIN_FAILED_LOGIN_THRESHOLD=5
    ADMIN_MIGRATION_SECRET=""
    NEXT_PUBLIC_ADMIN_USERS=""             # Admin user emails

    # MCP Resource Limits
    MCP_CPU_CORES_MAX=0.5                 # 50% of one core
    MCP_MEMORY_MAX_MB=512
    MCP_IO_READ_MBPS=10
    MCP_IO_WRITE_MBPS=5
    MCP_PROCESS_TIMEOUT_MS=300000         # 5 minutes
    MCP_STARTUP_TIMEOUT_MS=10000          # 10 seconds

    # Package Management
    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"
    MCP_PACKAGE_CACHE_DAYS=30
    MCP_PREWARM_COMMON_PACKAGES=true

    # Isolation Configuration
    MCP_ISOLATION_TYPE="bubblewrap"       # bubblewrap | firejail | none
    MCP_ISOLATION_FALLBACK="firejail"
    MCP_ENABLE_NETWORK_ISOLATION=false

    # Stripe Payments (Optional)
    STRIPE_SECRET_KEY=""
    STRIPE_WEBHOOK_SECRET=""
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=""
    ```
  </Tab>
</Tabs>

<Warning>
  **Security Requirements:**

  1. **Generate unique secrets** for each key using `openssl rand -base64 32`
  2. **Never commit** actual keys to version control
  3. **Use different keys** for NEXTAUTH\_SECRET and UNSUBSCRIBE\_TOKEN\_SECRET
  4. **Enable SSL** for production database connections
</Warning>

<Note>
  **Quick secret generation commands:**

  ```bash theme={null}
  # Generate all required secrets at once
  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)"
  echo "REGISTRY_INTERNAL_API_KEY=$(openssl rand -base64 32)"
  ```
</Note>

#### 4. Set Up Database

```bash theme={null}
# Create database
createdb pluggedin

# Run migrations
cd pluggedin-app
pnpm db:migrate

# Optional: Run auth migrations
pnpm db:migrate:auth
```

#### 5. Start the Applications

<CodeGroup>
  ```bash Development theme={null}
  # Terminal 1: Web application
  cd pluggedin-app
  pnpm dev

  # Terminal 2: MCP Proxy
  cd pluggedin-mcp
  npm run dev
  ```

  ```bash Production theme={null}
  # Build and start web application
  cd pluggedin-app
  pnpm build
  pnpm start

  # Build and start MCP proxy
  cd pluggedin-mcp
  npm run build
  npm start
  ```
</CodeGroup>

The application will be available at:

* Web Interface: `http://localhost:12005`
* MCP Proxy: `http://localhost:3000`

## Docker Installation (Recommended)

<Note>
  **🐳 Docker is the recommended installation method** - it includes PostgreSQL 18, automatic migrations, and optimized configuration out of the box.

  **NEW:** Multi-architecture support! Our Docker images now support both AMD64 (Intel/AMD) and ARM64 (Apple Silicon, AWS Graviton) platforms.
</Note>

### Option 1: Using Pre-built Images from Docker Hub (Fastest)

<Info>
  **Official multi-arch images are available on Docker Hub!** Automatically works on both AMD64 and ARM64 platforms.
</Info>

<Steps>
  <Step title="Pull Image">
    ```bash theme={null}
    # Docker automatically pulls the correct architecture for your platform
    docker pull veriteknik/pluggedin:latest

    # Or specific version
    docker pull veriteknik/pluggedin:v2.16.0
    ```
  </Step>

  <Step title="Download Docker Compose File">
    ```bash theme={null}
    # Download production compose file
    curl -O https://raw.githubusercontent.com/VeriTeknik/pluggedin-app/main/docker-compose.production.yml
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    # Create .env file
    cat > .env <<EOF
    DATABASE_URL=postgresql://pluggedin:pluggedin_secure_password@pluggedin-postgres:5432/pluggedin
    NEXTAUTH_URL=http://localhost:12005
    NEXTAUTH_SECRET=$(openssl rand -base64 32)
    NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=$(openssl rand -base64 32)
    PLUGGEDIN_API_KEY=$(openssl rand -base64 32)
    EOF
    ```
  </Step>

  <Step title="Start Services">
    ```bash theme={null}
    docker-compose -f docker-compose.production.yml up -d
    ```
  </Step>

  <Step title="Access Application">
    Open [http://localhost:12005](http://localhost:12005) in your browser
  </Step>
</Steps>

**Supported Architectures:**

* ✅ **AMD64 (x86\_64)** - Intel/AMD processors, most cloud platforms
* ✅ **ARM64 (aarch64)** - Apple Silicon (M1/M2/M3), AWS Graviton, Raspberry Pi 4+

### Option 2: Build from Source

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/VeriTeknik/pluggedin-app.git
    cd pluggedin-app
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    cp .env.example .env
    # Edit .env with your configuration (see environment variables section above)
    ```
  </Step>

  <Step title="Start Services">
    ```bash theme={null}
    docker-compose up --build -d
    ```
  </Step>

  <Step title="Access Application">
    Open [http://localhost:12005](http://localhost:12005) in your browser
  </Step>
</Steps>

### What's Included in Docker Setup

<CardGroup cols={2}>
  <Card title="Application Container" icon="cube">
    * Next.js 15 application
    * Node.js 20 runtime
    * MCP proxy integration
    * Port 12005 exposed
  </Card>

  <Card title="Database Container" icon="database">
    * PostgreSQL 18-alpine
    * Automatic migrations
    * Health checks
    * Persistent storage
  </Card>

  <Card title="Migrator Container" icon="rocket">
    * One-time setup (288 MB)
    * Drizzle ORM migrations
    * Auto-stops after completion
  </Card>

  <Card title="Persistent Volumes" icon="hard-drive">
    * Database data
    * User uploads
    * Application logs
    * MCP package cache
  </Card>
</CardGroup>

### Key Features

* ✅ PostgreSQL 18 (latest stable) with automatic migrations
* ✅ Optimized production build with health checks
* ✅ Persistent volumes for data safety
* ✅ Docker-optimized MCP isolation (no sandboxing overhead)
* ✅ Automatic restarts and health monitoring

### Advanced Docker Configuration

For detailed Docker deployment guides including:

* Production setup with Nginx
* Environment variable configuration
* PostgreSQL upgrade paths
* Backup strategies
* Troubleshooting

See the [Docker Deployment Guide](/deployment/docker).

## MCP Client Configuration

After installation, configure your MCP client to use Plugged.in.

### Claude Desktop

Add to your Claude configuration file:

<Tabs>
  <Tab title="macOS">
    Location: `~/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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Location: `%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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

Most MCP clients support similar configuration. Key points:

* **Command**: `node` or `npx`
* **Script**: Path to `pluggedin-mcp/dist/index.js`
* **API Key**: Your Plugged.in API key

## Verification

Verify your installation is working:

<Steps>
  <Step title="Check Web Interface">
    Navigate to `http://localhost:12005` and verify the page loads
  </Step>

  <Step title="Test Database">
    ```bash theme={null}
    cd pluggedin-app
    pnpm db:migrate
    ```
  </Step>

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

  <Step title="Test MCP Connection">
    Open your MCP client and verify it connects to Plugged.in
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database Connection Issues">
    * Verify PostgreSQL is running
    * Check DATABASE\_URL format
    * Ensure database exists
    * Check user permissions
  </Accordion>

  <Accordion title="Port Already in Use">
    Change the port in `.env`:

    ```bash theme={null}
    # Change web app port
    PORT=3001

    # Change MCP proxy port
    MCP_PORT=3002
    ```
  </Accordion>

  <Accordion title="Authentication Errors">
    * Regenerate NEXTAUTH\_SECRET
    * Clear browser cookies
    * Check NEXTAUTH\_URL matches your domain
  </Accordion>

  <Accordion title="MCP Client Not Connecting">
    * Verify API key is correct
    * Check MCP proxy is running
    * Review client configuration path
    * Check firewall settings
  </Accordion>
</AccordionGroup>

## Next Steps

* [Configure your installation](/quickstart/configuration)
* [Add MCP servers](/platform/registry)
* [Set up document library](/platform/overview)
* [Review security settings](/security/overview)

## Support

Need help? We're here to assist:

* [GitHub Issues](https://github.com/VeriTeknik/pluggedin-app/issues)
* [Community Discussions](https://github.com/orgs/VeriTeknik/discussions)
* API Support: [api-support@plugged.in](mailto:api-support@plugged.in)
* General Support: [support@plugged.in](mailto:support@plugged.in)