# Multi-Instance Configuration
Detailed guide for configuring multiple n8n environments.
---
## Configuration File Format
### .config.json Structure
```json
{
"environments": {
"[env-name]": {
"n8n_host": "https://n8n-url.com",
"n8n_api_key": "api-key"
}
},
"defaultEnv": "[env-name]"
}
```
### Field Specifications
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `environments` | Object | ✅ Yes | Collection of n8n instances |
| `defaultEnv` | String | ✅ Yes | Default environment identifier |
| `environments.[name]` | Object | ✅ Yes | Individual environment config |
| `n8n_host` | String | ✅ Yes | n8n base URL (no `/api/v1`) |
| `n8n_api_key` | String | ✅ Yes | n8n API authentication key |
---
## Configuration Examples
### Example 1: Dev + Prod
```json
{
"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
```json
{
"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
```json
{
"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:
```typescript
// 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
!!! danger "Never Commit .config.json"
```bash
# Add to .gitignore
echo ".config.json" >> .gitignore
# Verify
git status
# .config.json should NOT appear
```
### Separate Keys Per Environment
```json
{
"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
```bash
# 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:**
```bash
# 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:**
```json
{
"defaultEnv": "development" // Change this
}
```
---
## Next Steps
- [Environment Manager](environment-manager.md) - Architecture details
- [Instance Routing](instance-routing.md) - How routing works
- [Testing](testing.md) - Validate configuration
- [Examples](examples.md) - Real-world setups
---
!!! tip "Quick Start"
See [Installation Guide](../getting-started/installation/configuration.md) for step-by-step configuration instructions.
