> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt > Use this file to discover all available pages before exploring further. # Environment variables > Complete reference for all environment variables used by AgentMark 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](#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 ```bash theme={null} # .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](/concepts/environments) 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](/deploy/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) | ```bash theme={null} OPENAI_API_KEY=sk-xxxxx ``` ### Anthropic | Variable | Required | Description | | ------------------- | -------- | ----------------------------------- | | `ANTHROPIC_API_KEY` | Yes\* | Anthropic API key for Claude models | ```bash theme={null} ANTHROPIC_API_KEY=sk-ant-xxxxx ``` ### Google | Variable | Required | Description | | ------------------------------ | -------- | ----------------------------------- | | `GOOGLE_GENERATIVE_AI_API_KEY` | Yes\* | Google AI API key for Gemini models | ```bash theme={null} 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) | ```bash theme={null} 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) | ```bash theme={null} 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](https://github.com/github/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`. ```json agentmark.json theme={null} "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`: ```bash theme={null} 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](/observe/pii-masking#environment-variable-suppression). | | `AGENTMARK_HIDE_OUTPUTS` | No | `false` | Replace all output attributes with `[REDACTED]` before export. See [PII masking](/observe/pii-masking#environment-variable-suppression). | 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](/coding-agents/gateway-mcp): | 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`](/coding-agents/gateway-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:`). 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](/reference/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](/deploy/webhooks) 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](/deploy/webhooks). | ```bash theme={null} AGENTMARK_WEBHOOK_SECRET=whsec_xxxxx ``` ## Complete example Here's a complete `.env` file for a typical project: ```bash theme={null} # 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`: ```typescript theme={null} 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: