Environment Variables
This page documents all environment variables used by AgentMark, organized by purpose.
Create a .env file in your project root. The AgentMark CLI automatically loads it before running commands.
AgentMark Core
These variables configure AgentMark’s core functionality.
| Variable | Required | Default | Description |
|---|
AGENTMARK_API_KEY | Cloud only | - | Your AgentMark API key for cloud features. Get it from Dashboard > API Keys |
AGENTMARK_APP_ID | Cloud only | - | Your AgentMark application ID. Find it in Dashboard > Apps |
AGENTMARK_BASE_URL | No | http://localhost:9418 | Base URL for the local API server |
AGENTMARK_ENV | No | - | Set to development to use local loader (Python SDK) |
NODE_ENV | No | - | Set to development to use local loader (TypeScript SDK) |
TypeScript vs Python use different environment variables for detecting development mode:
- TypeScript: Checks
NODE_ENV === "development"
- Python: Checks
AGENTMARK_ENV == "development"
Set both if your project uses both languages, or configure your loader explicitly in code. Example: Development vs Production
# .env.development
NODE_ENV=development
AGENTMARK_BASE_URL=http://localhost:9418
# .env.production
NODE_ENV=production
AGENTMARK_API_KEY=am_live_xxxxx
AGENTMARK_APP_ID=app_xxxxx
AI Provider API Keys
Configure API keys for the AI providers you use. Only set the keys for providers you need.
OpenAI
| Variable | Required | Description |
|---|
OPENAI_API_KEY | Yes* | OpenAI API key for GPT models, DALL-E, TTS |
OPENAI_ORG_ID | No | Organization ID for OpenAI API calls |
OPENAI_BASE_URL | No | Custom base URL (for Azure OpenAI or proxies) |
Anthropic
| Variable | Required | Description |
|---|
ANTHROPIC_API_KEY | Yes* | Anthropic API key for Claude models |
ANTHROPIC_API_KEY=sk-ant-xxxxx
Google
| Variable | Required | Description |
|---|
GOOGLE_GENERATIVE_AI_API_KEY | Yes* | Google AI API key for Gemini models |
GOOGLE_GENERATIVE_AI_API_KEY=xxxxx
AWS Bedrock
| Variable | Required | Description |
|---|
AWS_ACCESS_KEY_ID | Yes* | AWS access key |
AWS_SECRET_ACCESS_KEY | Yes* | AWS secret key |
AWS_REGION | No | AWS region (default: us-east-1) |
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxxxx
AWS_REGION=us-west-2
Azure OpenAI
| Variable | Required | Description |
|---|
AZURE_OPENAI_API_KEY | Yes* | Azure OpenAI API key |
AZURE_OPENAI_ENDPOINT | Yes* | Azure OpenAI endpoint URL |
AZURE_OPENAI_API_VERSION | No | API version (default: 2024-02-15-preview) |
AZURE_OPENAI_API_KEY=xxxxx
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
*Required only if you use models from that provider. You don’t need to set keys for providers you don’t use.
MCP Server Configuration
Environment variables for MCP (Model Context Protocol) servers.
| Variable | Required | Default | Description |
|---|
AGENTMARK_MCP_SSE_URL | No | - | URL for SSE-based MCP servers |
GITHUB_TOKEN | No | - | GitHub personal access token for GitHub MCP server |
GITHUB_PERSONAL_ACCESS_TOKEN | No | - | Alternative name for GitHub token |
Using env() interpolation
You can reference environment variables in your MCP server config using env("VAR_NAME"):
const mcpServers = new McpServerRegistry({
docs: {
url: "env(MCP_DOCS_URL)",
headers: { Authorization: "Bearer env(MCP_AUTH_TOKEN)" },
},
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: { GITHUB_PERSONAL_ACCESS_TOKEN: "env(GITHUB_TOKEN)" },
},
});
.env:
MCP_DOCS_URL=https://docs.example.com/mcp
MCP_AUTH_TOKEN=your-auth-token
GITHUB_TOKEN=ghp_xxxxx
Observability & Tracing
Variables for telemetry and observability features.
| Variable | Required | Default | Description |
|---|
AGENTMARK_TRACING_ENABLED | No | true | Enable/disable tracing |
AGENTMARK_TRACING_ENDPOINT | No | AgentMark API | Custom OTLP endpoint for traces |
OTEL_EXPORTER_OTLP_ENDPOINT | No | - | Standard OpenTelemetry endpoint |
OTEL_EXPORTER_OTLP_HEADERS | No | - | Headers for OTLP exporter |
MCP Trace Server
For the MCP Trace Server:
| Variable | Required | Default | Description |
|---|
AGENTMARK_URL | No | http://localhost:9418 | AgentMark API server URL |
AGENTMARK_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds |
CLI Configuration
Variables that affect CLI behavior.
| Variable | Required | Default | Description |
|---|
AGENTMARK_DISABLE_UPDATE_CHECK | No | false | Set to 1 to disable update notifications |
DEBUG | No | - | Set to agentmark:* for verbose logging |
# Disable update checks
AGENTMARK_DISABLE_UPDATE_CHECK=1
# Enable debug logging
DEBUG=agentmark:*
Complete Example
Here’s a complete .env file for a typical project:
# AgentMark Configuration
AGENTMARK_API_KEY=am_live_xxxxx
AGENTMARK_APP_ID=app_xxxxx
# AI Provider Keys (only include providers you use)
OPENAI_API_KEY=sk-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
# MCP Servers
GITHUB_TOKEN=ghp_xxxxx
# Development overrides (uncomment for local dev)
# NODE_ENV=development
# AGENTMARK_BASE_URL=http://localhost:9418
Loading Environment Variables
Automatic Loading
The AgentMark CLI automatically loads .env files from your project root before running any command.
Manual Loading (Application Code)
For your application code, use a package like dotenv:
import "dotenv/config";
// Now process.env.AGENTMARK_API_KEY is available
.env.local are loaded automatically.
CI/CD
In CI/CD environments, set environment variables through your platform’s secrets management:
- GitHub Actions: Repository secrets or environment secrets
- Vercel: Project environment variables
- AWS: Secrets Manager or Parameter Store
Have Questions?
We’re here to help! Choose the best way to reach us:
