Environment variables - AgentMark Docs

Create a .env file in your project root. The AgentMark CLI automatically loads it before running commands.

AgentMark core

Variable	Required	Default	Description
`AGENTMARK_API_KEY`	Cloud only	None	Your AgentMark API key. Generate one from the API Keys page in your app’s settings (Dashboard → your app → Settings → API Keys).
`AGENTMARK_APP_ID`	Cloud only	None	Your AgentMark application ID. Find it on your app’s settings page (Dashboard → your app → Settings → General).
`AGENTMARK_BASE_URL`	No	`https://api.agentmark.co`	Base URL for the AgentMark API, read by `ApiLoader.cloud()`. Override only when self-hosting or targeting a staging environment.

The scaffolded client routes automatically: AGENTMARK_API_KEY present → ApiLoader.cloud; absent → ApiLoader.local (local dev server). No extra env vars needed.

Don’t confuse AGENTMARK_BASE_URL with AGENTMARK_API_URL (see CLI configuration). They share the same default (https://api.agentmark.co) but different code paths read them: AGENTMARK_BASE_URL configures the SDK/client loader (ApiLoader.cloud()), while AGENTMARK_API_URL configures CLI tooling: agentmark run-experiment’s baseline fetch and the agentmark-mcp server. Set the one that matches what you’re running.

Example: local dev vs cloud

# .env (local dev — no API key, routes to local dev server automatically)
OPENAI_API_KEY=sk-...

# .env (cloud / CI — API key present, routes to AgentMark Cloud automatically)
AGENTMARK_API_KEY=sk_agentmark_xxxxx
AGENTMARK_APP_ID=a1b2c3d4-5678-90ab-cdef-1234567890ab
OPENAI_API_KEY=sk-...

AI provider API keys

Configure API keys for the AI providers you use. Only set the keys for providers you actually call.

When you set these in the AgentMark Dashboard (your app → Settings → Environment variables), AgentMark stores the values encrypted in the vault, scopes them to the app, decrypts them only at runtime, and keeps them out of logs. Each variable targets one or more environment kinds (Development, Preview, Production, or All Environments) or a single specific environment, with the most specific target winning, so a fresh Preview environment inherits the Preview and All-Environments keys it was never configured with. See Security → Provider API keys for the storage details.

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)

OPENAI_API_KEY=sk-xxxxx

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`	Yes*	AWS region (delegated to AWS SDK; no AgentMark default)

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`	Yes*	API version (delegated to the Azure SDK; no AgentMark default)

AZURE_OPENAI_API_KEY=xxxxx
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-06-01

*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

AgentMark doesn’t read any MCP-specific env vars itself. MCP servers reference whatever env vars you configure in your agentmark.json mcpServers block or pass via env: to a stdio server:

Variable	Purpose
`GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN`	Used by the GitHub MCP server when referenced via `env('GITHUB_TOKEN')`
Any others	Anything you reference via `env('VAR_NAME')` interpolation

Using `env()` interpolation

Reference environment variables in the mcpServers block of your agentmark.json with env('VAR_NAME') (single or double quotes). Variable names must be uppercase letters, digits, and underscores. Interpolation is whole-string only: the entire value must be the env(...) expression, so a composed string like "Bearer env('TOKEN')" passes through literally. Put the full value, prefix included, in the variable itself. Values resolve from the process environment when AgentMark connects the MCP server; a missing variable throws Missing environment variable: VAR_NAME.

agentmark.json

"mcpServers": {
  "docs": {
    "url": "env('MCP_DOCS_URL')",
    "headers": {
      "Authorization": "env('MCP_AUTH_HEADER')"
    }
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "env('GITHUB_TOKEN')"
    }
  }
}

Then set the variables in .env:

MCP_DOCS_URL=https://docs.example.com/mcp
MCP_AUTH_HEADER="Bearer your-auth-token"
GITHUB_TOKEN=ghp_xxxxx

Observability and tracing

Variable	Required	Default	Description
`AGENTMARK_HIDE_INPUTS`	No	`false`	Replace all input attributes with `[REDACTED]` before export. See PII masking.
`AGENTMARK_HIDE_OUTPUTS`	No	`false`	Replace all output attributes with `[REDACTED]` before export. See PII masking.

You control tracing by calling sdk.initTracing() in your code, not through an environment variable. The SDK derives the OTLP endpoint from its configured baseUrl, and you can’t override it via OTEL_EXPORTER_OTLP_ENDPOINT.

Gateway MCP server

For the gateway MCP server:

Variable	Required	Default	Description
`AGENTMARK_API_URL`	No	`https://api.agentmark.co`	Gateway URL; set to `http://localhost:9418` for the local dev server
`AGENTMARK_API_KEY`	No	None	Forwarded as the API key when the gateway MCP calls the AgentMark API
`AGENTMARK_TIMEOUT_MS`	No	`30000`	Request timeout in milliseconds

CLI configuration

Variable	Required	Default	Description
`AGENTMARK_API_PORT`	No	`9418`	Port of the local API server that `agentmark run-experiment`’s score-posting step calls back to. To change the port that `agentmark dev` binds, pass `--api-port` instead.
`AGENTMARK_API_URL`	No	`https://api.agentmark.co`	AgentMark Cloud gateway URL. Used by the `agentmark-mcp` MCP server and read by `agentmark run-experiment` when fetching baseline scores from Cloud (the regression gate). Distinct from `AGENTMARK_BASE_URL`, the SDK/client loader’s URL.
`AGENTMARK_DEV_SERVER`	No	None	Set by `agentmark dev` in the spawned dev runner’s environment; points at the local API server (`http://localhost:<api-port>`). The CLI also removes `AGENTMARK_API_KEY`, `AGENTMARK_APP_ID`, and `AGENTMARK_BASE_URL` from that environment so the runner stays in local mode. Read by the scaffolded Python dev server.
`AGENTMARK_WEBHOOK_URL`	No	`http://localhost:9417`	Override the webhook server URL for `agentmark run-prompt` and `agentmark run-experiment`.
`AGENTMARK_NO_UPDATE_NOTIFIER`	No	None	Set to any truthy value to suppress the CLI’s upgrade-available banner. See `cli-src/update-notifier/constants.ts:15`.

Webhook configuration

Variables for alert webhook endpoints.

Variable	Required	Default	Description
`AGENTMARK_WEBHOOK_SECRET`	Webhook only	None	Secret for verifying alert webhook signatures, shown in the Dashboard under your app’s Settings → Integrations → Webhook Url form. This is a user-code convention; AgentMark’s SDK doesn’t read this variable, and your webhook handler passes it to `verifySignature()`. Only needed if you deploy a webhook endpoint for alert notifications.

AGENTMARK_WEBHOOK_SECRET=whsec_xxxxx

Complete example

Here’s a complete .env file for a typical project:

# AgentMark configuration
AGENTMARK_API_KEY=sk_agentmark_xxxxx
AGENTMARK_APP_ID=a1b2c3d4-5678-90ab-cdef-1234567890ab

# 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

# Alert webhook (only if using webhook endpoint)
# AGENTMARK_WEBHOOK_SECRET=whsec_xxxxx

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

Or in Next.js, the framework loads environment variables from .env.local automatically.

CI/CD

In CI/CD, set environment variables through your CI/CD provider’s secrets management:

GitHub Actions: repository secrets or environment secrets
Vercel: project environment variables
AWS: Secrets Manager or Parameter Store

Have questions?

Reach out any time:

Email the team at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about AgentMark’s business solutions

​AgentMark core

​Example: local dev vs cloud

​AI provider API keys

​OpenAI

​Anthropic

​Google

​AWS Bedrock

​Azure OpenAI

​MCP server configuration

​Using env() interpolation

​Observability and tracing

​Gateway MCP server

​CLI configuration

​Webhook configuration

​Complete example

​Loading environment variables

​Automatic loading

​Manual loading (application code)

​CI/CD

​Have questions?

AgentMark core

Example: local dev vs cloud

AI provider API keys

OpenAI

Anthropic

Google

AWS Bedrock

Azure OpenAI

MCP server configuration

Using `env()` interpolation

Observability and tracing

Gateway MCP server

CLI configuration

Webhook configuration

Complete example

Loading environment variables

Automatic loading

Manual loading (application code)

CI/CD

Have questions?