> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/darkzOGx/youtube-automation-agent/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Deployment

> Run the YouTube Automation Agent on your local machine for development and testing

## Overview

Local deployment is the simplest way to get started with the YouTube Automation Agent. This option is perfect for:

* Testing and development
* Running automation on your personal computer
* Small-scale operations (1-2 videos per day)
* Learning how the system works

<Note>
  Local deployment is **completely free** but requires your computer to be running for automation to work.
</Note>

## Prerequisites

<CardGroup cols={2}>
  <Card title="Node.js 18+" icon="node-js">
    Download from [nodejs.org](https://nodejs.org/)
  </Card>

  <Card title="Google Account" icon="google">
    For YouTube API access
  </Card>

  <Card title="AI Provider" icon="brain">
    OpenAI or Google Gemini account
  </Card>

  <Card title="10 Minutes" icon="clock">
    For initial setup and configuration
  </Card>
</CardGroup>

## System Requirements

| Component    | Minimum                               | Recommended     |
| ------------ | ------------------------------------- | --------------- |
| **CPU**      | Dual-core                             | Quad-core       |
| **RAM**      | 2 GB                                  | 4 GB            |
| **Storage**  | 500 MB                                | 2 GB            |
| **OS**       | Windows 10, macOS 10.15, Ubuntu 18.04 | Latest versions |
| **Internet** | Stable broadband connection           |                 |

## Installation Steps

<Steps>
  <Step title="Install Node.js">
    Download and install Node.js 18 or higher from [nodejs.org](https://nodejs.org/)

    Verify installation:

    ```bash theme={null}
    node --version  # Should show v18.0.0 or higher
    npm --version   # Should show 9.0.0 or higher
    ```
  </Step>

  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/darkzOGx/youtube-automation-agent.git
    cd youtube-automation-agent
    ```
  </Step>

  <Step title="Install Dependencies">
    Install all required npm packages:

    ```bash theme={null}
    npm install
    ```

    This will install:

    * Express server (port 3456)
    * Google APIs for YouTube
    * AI libraries (OpenAI, Google Generative AI)
    * Database (SQLite3)
    * Automation schedulers (node-cron)
    * And all other dependencies
  </Step>

  <Step title="Configure Environment Variables">
    Copy the example environment file:

    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` with your preferred text editor and fill in:

    ```env theme={null}
    # Application Settings
    NODE_ENV=production
    PORT=3456
    LOG_LEVEL=info

    # AI Provider (choose one)
    OPENAI_API_KEY=sk-your-openai-key-here
    # OR
    GEMINI_API_KEY=your-gemini-key-here

    # Channel Settings
    CHANNEL_NAME=Your Channel Name
    DEFAULT_AUTHOR=Your Name
    TARGET_AUDIENCE=Your target audience

    # YouTube Settings
    YOUTUBE_REGION=US
    DEFAULT_PRIVACY_STATUS=public

    # Security
    JWT_SECRET=generate-a-random-secret-here
    ```
  </Step>

  <Step title="Set Up YouTube API Credentials">
    1. Go to [Google Cloud Console](https://console.cloud.google.com/)
    2. Create a new project or select existing one
    3. Enable YouTube Data API v3
    4. Create OAuth 2.0 credentials (Desktop app)
    5. Download the JSON file
    6. Save it as `config/credentials.json`

    <Warning>
      Keep your `credentials.json` file secure and never commit it to version control!
    </Warning>
  </Step>

  <Step title="Run Interactive Setup">
    The setup wizard will guide you through configuration:

    ```bash theme={null}
    npm run setup
    ```

    This will:

    * Verify your credentials
    * Initialize the database
    * Configure your channel preferences
    * Set up automation schedules
  </Step>

  <Step title="Start the Agent">
    Start the main application:

    ```bash theme={null}
    npm start
    ```

    You should see:

    ```
    ✓ Database initialized
    ✓ YouTube API connected
    ✓ AI service initialized
    ✓ Server running on http://localhost:3456
    ✓ Automation scheduler started
    ```
  </Step>

  <Step title="Access the Dashboard">
    Open your browser and navigate to:

    ```
    http://localhost:3456
    ```

    The dashboard provides:

    * Real-time automation status
    * Content generation controls
    * Analytics and performance metrics
    * Publishing schedule management
  </Step>
</Steps>

## Available NPM Scripts

### Core Commands

```bash theme={null}
# Start the main application
npm start

# Run initial setup wizard
npm run setup

# Start daily automation scheduler
npm run scheduler

# Run system tests
npm run test
```

### Agent Commands

Run individual agents manually:

```bash theme={null}
npm run agent:strategy      # Content strategy planning
npm run agent:script        # Script writing
npm run agent:thumbnail     # Thumbnail generation
npm run agent:seo           # SEO optimization
npm run agent:production    # Production management
npm run agent:publishing    # Publishing & scheduling
npm run agent:analytics     # Analytics & optimization
```

### Database Commands

```bash theme={null}
npm run db:init             # Initialize database
npm run credentials:setup   # Set up OAuth credentials
```

## Automation Schedule

Once running, the agent operates on this schedule:

| Time             | Task                 | Description                      |
| ---------------- | -------------------- | -------------------------------- |
| **6:00 AM**      | Content Generation   | Strategy, script, thumbnail, SEO |
| **Every 15 min** | Publishing Queue     | Processes scheduled uploads      |
| **9:00 AM**      | Analytics Collection | Gathers performance data         |
| **10:00 PM**     | Optimization         | Runs improvement tasks           |
| **Weekly**       | Strategy Review      | Performance analysis             |

<Note>
  All times are based on your system's local timezone.
</Note>

## Manual Content Generation

Generate content on-demand using the API:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST http://localhost:3456/generate \
      -H "Content-Type: application/json" \
      -d '{
        "topic": "10 Productivity Tips for 2026",
        "style": "listicle"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('http://localhost:3456/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        topic: '10 Productivity Tips for 2026',
        style: 'listicle'
      })
    });
    const result = await response.json();
    console.log(result);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post('http://localhost:3456/generate',
      json={
        'topic': '10 Productivity Tips for 2026',
        'style': 'listicle'
      }
    )
    print(response.json())
    ```
  </Tab>
</Tabs>

## Monitoring and Logs

### View Real-time Logs

```bash theme={null}
# View application logs
tail -f logs/app.log

# View error logs
tail -f logs/error.log

# View agent-specific logs
tail -f logs/agents/*.log
```

### Health Check

```bash theme={null}
curl http://localhost:3456/health
```

Expected response:

```json theme={null}
{
  "status": "healthy",
  "uptime": 3600,
  "database": "connected",
  "youtube": "authenticated",
  "ai_service": "ready"
}
```

## Running in Background

<Tabs>
  <Tab title="macOS/Linux">
    Using `nohup`:

    ```bash theme={null}
    nohup npm start > output.log 2>&1 &
    ```

    Using `screen`:

    ```bash theme={null}
    screen -S youtube-agent
    npm start
    # Press Ctrl+A, then D to detach

    # Reattach later:
    screen -r youtube-agent
    ```
  </Tab>

  <Tab title="Windows">
    Using `pm2` (recommended):

    ```bash theme={null}
    npm install -g pm2
    pm2 start index.js --name youtube-agent
    pm2 save
    pm2 startup
    ```

    View logs:

    ```bash theme={null}
    pm2 logs youtube-agent
    ```
  </Tab>
</Tabs>

## Troubleshooting

### Port Already in Use

If port 3456 is already in use:

```env theme={null}
# Change port in .env
PORT=3457
```

### YouTube API Quota Exceeded

* Check [Google Cloud Console](https://console.cloud.google.com/) quotas
* Default limit: 10,000 units/day (sufficient for most use cases)
* Implement rate limiting by adjusting schedule frequency

### AI Service Connection Failed

<Steps>
  <Step title="Verify API Key">
    Check that your API key is correct in `.env`
  </Step>

  <Step title="Check Credits">
    For OpenAI: Ensure you have available credits
    For Gemini: Verify API is enabled
  </Step>

  <Step title="Test Connection">
    ```bash theme={null}
    npm run test
    ```
  </Step>
</Steps>

### Database Errors

Reinitialize the database:

```bash theme={null}
# Backup existing data
cp data/youtube-automation.db data/youtube-automation.db.backup

# Reinitialize
npm run db:init
```

## Stopping the Agent

<Tabs>
  <Tab title="Foreground Process">
    Press `Ctrl+C` in the terminal
  </Tab>

  <Tab title="Background Process">
    ```bash theme={null}
    # Using pm2
    pm2 stop youtube-agent

    # Using process ID
    ps aux | grep node
    kill <PID>
    ```
  </Tab>
</Tabs>

## Data and Backups

### Important Directories

* `data/` - Generated content, thumbnails, and database
* `logs/` - Application and error logs
* `uploads/` - Temporary upload files
* `config/` - Credentials and configuration

### Backup Recommendations

```bash theme={null}
# Create backup
tar -czf youtube-agent-backup-$(date +%Y%m%d).tar.gz \
  data/ config/ .env

# Restore from backup
tar -xzf youtube-agent-backup-20260305.tar.gz
```

<Warning>
  Always backup before major updates or configuration changes!
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="VPS Deployment" icon="server" href="/deployment/vps">
    Deploy to a VPS for 24/7 operation
  </Card>

  <Card title="Cloud Deployment" icon="cloud" href="/deployment/cloud">
    Scale with cloud platforms
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment">
    Advanced configuration options
  </Card>

  <Card title="API Reference" icon="code" href="/api/endpoints">
    Explore API endpoints
  </Card>
</CardGroup>