Installation Guide

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

🚀 Recommended: Use Plugged.in Cloud 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.

Quick Start (Cloud Platform - Recommended)

The fastest way to get started is using our hosted platform at plugged.in. No installation required!

Create your account at plugged.in/register

Configure MCP Proxy

Install the MCP proxy following the instructions in your dashboard

Add MCP Servers

Browse and add servers from the registry or configure your own

Connect Your Client

Use the generated configuration with Claude, Cursor, or other MCP clients

Self-Hosting

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

Prerequisites

System Requirements

Node.js 18+ or 20+
PostgreSQL 15+ (18+ recommended)
2GB+ RAM
10GB+ storage

Optional Services

Redis (for caching)
SMTP server (for emails)
S3-compatible storage

Installation Steps

1. Clone the Repositories

git clone https://github.com/VeriTeknik/pluggedin-app.git
cd pluggedin-app

2. Install Dependencies

pnpm (recommended)
npm

# Web application
cd pluggedin-app
pnpm install

# MCP Proxy
cd ../pluggedin-mcp
npm install

# Web application
cd pluggedin-app
npm install

# MCP Proxy
cd ../pluggedin-mcp
npm install

3. Configure Environment Variables

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

Required Configuration
Email Configuration
OAuth Providers
AI & Registry
Advanced Settings

# 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

# Email Server (Optional but recommended)
EMAIL_FROM="[email protected]"
EMAIL_FROM_NAME="Pluggedin"
EMAIL_REPLY_TO="[email protected]"
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

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

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

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

Security Requirements:

Generate unique secrets for each key using openssl rand -base64 32
Never commit actual keys to version control
Use different keys for NEXTAUTH_SECRET and UNSUBSCRIBE_TOKEN_SECRET
Enable SSL for production database connections

Quick secret generation commands:

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

4. Set Up Database

# Create database
createdb pluggedin

# Run migrations
cd pluggedin-app
pnpm db:migrate

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

5. Start the Applications

# Terminal 1: Web application
cd pluggedin-app
pnpm dev

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

The application will be available at:

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

Docker Installation (Recommended)

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

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

Official multi-arch images are available on Docker Hub! Automatically works on both AMD64 and ARM64 platforms.

Pull Image

# Docker automatically pulls the correct architecture for your platform
docker pull veriteknik/pluggedin:latest

# Or specific version
docker pull veriteknik/pluggedin:v2.16.0

Download Docker Compose File

# Download production compose file
curl -O https://raw.githubusercontent.com/VeriTeknik/pluggedin-app/main/docker-compose.production.yml

Configure Environment

# 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

Start Services

docker-compose -f docker-compose.production.yml up -d

Access Application

Open http://localhost:12005 in your browser

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

Clone Repository

git clone https://github.com/VeriTeknik/pluggedin-app.git
cd pluggedin-app

Configure Environment

cp .env.example .env
# Edit .env with your configuration (see environment variables section above)

Start Services

docker-compose up --build -d

Access Application

Open http://localhost:12005 in your browser

What’s Included in Docker Setup

Application Container

Next.js 15 application
Node.js 20 runtime
MCP proxy integration
Port 12005 exposed

Database Container

PostgreSQL 18-alpine
Automatic migrations
Health checks
Persistent storage

Migrator Container

One-time setup (288 MB)
Drizzle ORM migrations
Auto-stops after completion

Persistent Volumes

Database data
User uploads
Application logs
MCP package cache

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.

MCP Client Configuration

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

Claude Desktop

Add to your Claude configuration file:

macOS
Windows

Location: ~/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"
      }
    }
  }
}

Location: %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"
      }
    }
  }
}

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:

Check Web Interface

Navigate to http://localhost:12005 and verify the page loads

Test Database

cd pluggedin-app
pnpm db:migrate

Verify MCP Proxy

curl http://localhost:3000/health

Test MCP Connection

Open your MCP client and verify it connects to Plugged.in

Troubleshooting

Database Connection Issues

Verify PostgreSQL is running
Check DATABASE_URL format
Ensure database exists
Check user permissions

Port Already in Use

Change the port in .env:

# Change web app port
PORT=3001

# Change MCP proxy port
MCP_PORT=3002

Authentication Errors

Regenerate NEXTAUTH_SECRET
Clear browser cookies
Check NEXTAUTH_URL matches your domain

MCP Client Not Connecting

Verify API key is correct
Check MCP proxy is running
Review client configuration path
Check firewall settings

Next Steps

Support

Need help? We’re here to assist:

Getting Started

Platform Features

PAP Agents

Tutorials

Security

Deployment

Observability

Testing

Migration Guides

Troubleshooting

Advanced Configuration

Integration Guides

Performance

​Installation Guide

​Quick Start (Cloud Platform - Recommended)

​Self-Hosting

​Prerequisites

System Requirements

Optional Services

​Installation Steps

​1. Clone the Repositories

​2. Install Dependencies

​3. Configure Environment Variables

​4. Set Up Database

​5. Start the Applications

​Docker Installation (Recommended)

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

​Option 2: Build from Source

​What’s Included in Docker Setup

Application Container

Database Container

Migrator Container

Persistent Volumes

​Key Features

​Advanced Docker Configuration

​MCP Client Configuration

​Claude Desktop

​Other MCP Clients

​Verification

​Troubleshooting

​Next Steps

​Support

Installation Guide

Quick Start (Cloud Platform - Recommended)

Self-Hosting

Prerequisites

Installation Steps

1. Clone the Repositories

2. Install Dependencies

3. Configure Environment Variables

4. Set Up Database

5. Start the Applications

Docker Installation (Recommended)

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

Option 2: Build from Source

What’s Included in Docker Setup

Key Features

Advanced Docker Configuration

MCP Client Configuration

Claude Desktop

Other MCP Clients

Verification

Troubleshooting

Next Steps

Support