Multi-Instance Configuration¶

Detailed guide for configuring multiple n8n environments.

Configuration File Format¶

.config.json Structure¶

{
  "environments": {
    "[env-name]": {
      "n8n_host": "https://n8n-url.com",
      "n8n_api_key": "api-key"
    }
  },
  "defaultEnv": "[env-name]"
}

Field Specifications¶

Configuration Examples¶

Example 1: Dev + Prod¶

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.mycompany.com",
      "n8n_api_key": "n8n_api_prod_xyz789"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "n8n_api_dev_abc123"
    }
  },
  "defaultEnv": "development"
}

Example 2: Full Stack¶

{
  "environments": {
    "production": {
      "n8n_host": "https://prod.n8n.example.com",
      "n8n_api_key": "prod_key_here"
    },
    "staging": {
      "n8n_host": "https://staging.n8n.example.com",
      "n8n_api_key": "staging_key_here"
    },
    "qa": {
      "n8n_host": "https://qa.n8n.example.com",
      "n8n_api_key": "qa_key_here"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "dev_key_here"
    }
  },
  "defaultEnv": "development"
}

Example 3: Geographic Distribution¶

{
  "environments": {
    "us-east": {
      "n8n_host": "https://n8n-us.example.com",
      "n8n_api_key": "us_key"
    },
    "eu-west": {
      "n8n_host": "https://n8n-eu.example.com",
      "n8n_api_key": "eu_key"
    },
    "asia-pacific": {
      "n8n_host": "https://n8n-apac.example.com",
      "n8n_api_key": "apac_key"
    }
  },
  "defaultEnv": "us-east"
}

Environment Naming¶

Best Practices¶

Standard Names: - production - Live environment - staging - Pre-production testing - development - Local development - qa - Quality assurance testing

Custom Names: - demo - Demo/showcase environment - backup - Backup instance - migration - Migration testing - Geographic: us-east, eu-west

Naming Rules: - Use lowercase - Use hyphens, not underscores: us-east not us_east - Be descriptive: production-eu not prod1 - Avoid special characters

Configuration Validation¶

Startup Validation¶

On server start, configuration is validated:

✅ Configuration loaded: 3 environment(s)
✅ Default environment: development
✅ Environments:
   - production: https://prod.n8n.example.com
   - staging: https://staging.n8n.example.com
   - development: http://localhost:5678

Runtime Validation¶

When tools are invoked:

// Valid instance
list_workflows({ instance: "production" })
→ Routes to production

// Invalid instance
list_workflows({ instance: "nonexistent" })
→ Error: Instance 'nonexistent' not found.
   Available: production, staging, development

Security Best Practices¶

API Key Management¶

# Add to .gitignore
echo ".config.json" >> .gitignore

# Verify
git status
# .config.json should NOT appear

Separate Keys Per Environment¶

{
  "environments": {
    "production": {
      "n8n_api_key": "PROD_KEY_DIFFERENT"
    },
    "development": {
      "n8n_api_key": "DEV_KEY_DIFFERENT"
    }
  }
}

Benefits: - Limit blast radius if key compromised - Easy key rotation per environment - Environment-specific permissions

File Permissions¶

# Restrict access
chmod 600 .config.json

# Verify
ls -la .config.json
# Should show: -rw------- (600)

Troubleshooting¶

Configuration Not Loaded¶

Symptom: Server uses .env instead of .config.json

Solution:

# Verify .config.json exists
ls -la .config.json

# Check JSON syntax
cat .config.json | python3 -m json.tool

# Restart server
npx @kernel.salacoste/n8n-workflow-builder

Instance Not Found¶

Symptom: "Instance 'staging' not found"

Solution: 1. Check environment name in .config.json 2. Verify exact spelling (case-sensitive) 3. List available instances in config 4. Use correct instance name

Wrong Default Instance¶

Symptom: Commands use wrong environment by default

Solution:

{
  "defaultEnv": "development"  // Change this
}

Next Steps¶

• Environment Manager - Architecture details
• Instance Routing - How routing works
• Testing - Validate configuration
• Examples - Real-world setups