Environment variables - AgentMark Docs

This page documents the environment variables AgentMark actually reads, organized by purpose. Every entry below was verified by grepping process.env.<NAME> and os.environ references in the repo at HEAD.

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	—	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	—	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 read by the Python `ApiLoader.cloud()` (defaults to `https://api.agentmark.co`) and the scaffolded TypeScript `agentmark.client.ts` when `NODE_ENV === 'development'` (where the TS scaffold falls back to `http://localhost:9418`).
`NODE_ENV`	No	—	The scaffolded TypeScript client branches on `NODE_ENV === 'development'` to pick `ApiLoader.local` vs `ApiLoader.cloud`. The Python scaffold does not read `NODE_ENV` — it uses `ApiLoader.cloud()` directly and relies on the CLI setting `AGENTMARK_BASE_URL` for local dev. The SDK itself never branches on `NODE_ENV`.

NODE_ENV is a user-code convention in the scaffolded TypeScript client, not something the SDK reads internally. If you write your own client, pick whatever flag fits your setup.

Example: development vs production

The scaffolded TypeScript client uses NODE_ENV to decide which loader to use. A typical setup:

# .env (development)
NODE_ENV=development
AGENTMARK_BASE_URL=http://localhost:9418

# .env (production)
NODE_ENV=production
AGENTMARK_API_KEY=sk_agentmark_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 actually call.

When set on a managed AgentMark Cloud deployment (Dashboard → your app → Settings → Environment variables), values are stored encrypted in our vault, scoped to the app, decrypted only at build time, and excluded from logs. See Security → Provider API keys for 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 does not 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

You can reference environment variables in your MCP server config using env("VAR_NAME"):

const mcpServers = {
  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)" },
  },
};

const client = createAgentMarkClient({
  mcpServers,
  // ... other options
});

Then set the variables in .env:

MCP_DOCS_URL=https://docs.example.com/mcp
MCP_AUTH_TOKEN=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.

Tracing is controlled by calling sdk.initTracing() in your code, not by an environment variable. The OTLP endpoint is derived from the SDK’s configured baseUrl and is not overridable via OTEL_EXPORTER_OTLP_ENDPOINT. The Claude Agent SDK adapter actively strips OTEL_EXPORTER_OTLP_ENDPOINT from child processes to prevent duplicate spans.

MCP trace server

For the MCP trace server:

Variable	Required	Default	Description
`AGENTMARK_URL`	No	`http://localhost:9418`	AgentMark API server URL
`AGENTMARK_API_KEY`	No	—	Forwarded as the API key when the MCP trace server 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 (`AGENTMARK_API_URL=https://api-stg.agentmark.co` points it at staging) and read by `agentmark run-experiment` when posting scores to Cloud.
`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	—	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	—	Secret for verifying alert webhook signatures, shown in the dashboard under your app’s Settings → Integrations → LLM Call URL form. This is a user-code convention — AgentMark’s SDK does not read this variable; 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=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

# Alert webhook (only if using webhook endpoint)
# AGENTMARK_WEBHOOK_SECRET=whsec_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

Or in Next.js, environment variables from .env.local are loaded 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?

We’re here to help! Choose the best way to reach us:

Email us at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about our business solutions

Documentation Index

​AgentMark core

​Example: development vs production

​AI provider API keys

​OpenAI

​Anthropic

​Google

​AWS Bedrock

​Azure OpenAI

​MCP server configuration

​Using env() interpolation

​Observability and tracing

​MCP trace server

​CLI configuration

​Webhook configuration

​Complete example

​Loading environment variables

​Automatic loading

​Manual loading (application code)

​CI/CD

​Have Questions?

AgentMark core

Example: development vs production

AI provider API keys

OpenAI

Anthropic

Google

AWS Bedrock

Azure OpenAI

MCP server configuration

Using `env()` interpolation

Observability and tracing

MCP trace server

CLI configuration

Webhook configuration

Complete example

Loading environment variables

Automatic loading

Manual loading (application code)

CI/CD

Have Questions?