Properly configuring environment variables is crucial for security and flexibility when using Metorial with the AI SDK.

Required Environment Variables

Metorial API Key

METORIAL_API_KEY=your-metorial-api-key-here

This authenticates your application with Metorial's platform.

Model Provider API Keys

Depending on which AI model you're using:

# For OpenAI
OPENAI_API_KEY=your-openai-key

# For Anthropic
ANTHROPIC_API_KEY=your-anthropic-key

# For Google
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key

Server Deployment ID

While not required as an environment variable, it's a good practice:

SERVER_DEPLOYMENT_ID=your-deployment-id

Setting Up Environment Variables

Local Development

Create a .env file in your project root:

METORIAL_API_KEY=mtl_xxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
SERVER_DEPLOYMENT_ID=deployment-xxxxx

Important: Add .env to your .gitignore:

.env
.env.local
.env.*.local

Loading Environment Variables

Most frameworks load .env automatically. For Node.js, use dotenv:

npm install dotenv

import 'dotenv/config';
// Now process.env.METORIAL_API_KEY is available

Vercel Deployment

1. Go to your project settings in Vercel
2. Navigate to "Environment Variables"
3. Add your variables for each environment (Production, Preview, Development)

Other Platforms

• Netlify: Site settings → Environment variables
• AWS: Use AWS Secrets Manager or Systems Manager Parameter Store
• Docker: Use --env-file flag or environment sections in docker-compose.yml

Using Configuration in Code

Basic Setup

import { Metorial } from 'metorial';

const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY!
});

await metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: [process.env.SERVER_DEPLOYMENT_ID!]
  },
  async session => {
    // Your code here
  }
);

Validation

Always validate environment variables at startup:

const requiredEnvVars = [
  'METORIAL_API_KEY',
  'OPENAI_API_KEY',
  'SERVER_DEPLOYMENT_ID'
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

Configuration Object Pattern

For larger applications, create a configuration module:

// config.ts
export const config = {
  metorial: {
    apiKey: process.env.METORIAL_API_KEY!,
    deploymentId: process.env.SERVER_DEPLOYMENT_ID!
  },
  openai: {
    apiKey: process.env.OPENAI_API_KEY!
  }
};

// Validate on import
if (!config.metorial.apiKey) {
  throw new Error('METORIAL_API_KEY is required');
}

Different Environments

Use different variables for different environments:

# .env.development
METORIAL_API_KEY=mtl_dev_xxxxx
SERVER_DEPLOYMENT_ID=dev-deployment-id

# .env.production
METORIAL_API_KEY=mtl_prod_xxxxx
SERVER_DEPLOYMENT_ID=prod-deployment-id

Security Best Practices

1. Never commit API keys to version control
2. Rotate keys regularly (every 90 days recommended)
3. Use different keys for different environments
4. Restrict key permissions in your Metorial dashboard
5. Monitor key usage for unusual activity
6. Revoke compromised keys immediately

Troubleshooting

"Environment variable not found"

• Check your .env file exists
• Verify the variable names match exactly
• Restart your development server after changes
• Ensure .env is in the correct directory

"Invalid API key" in production

• Verify environment variables are set in your deployment platform
• Check for extra spaces or quotes around values
• Ensure you're using production keys, not development keys