Environment Variables¶

This page documents all environment variables used across the Coalex platform -- SDK configuration, infrastructure services, publishing, and LLM provider credentials.

Never hardcode secrets

Always use environment variables or a secrets manager. Never commit API keys, tokens, or credentials to source control.

SDK Variables¶

These variables configure the Coalex SDKs (Python and TypeScript) in your agent.

Variable	Required	Default	Description
`COALEX_API_KEY`	Yes	--	API key for authenticating with the Coalex proxy. Generate from the admin dashboard (Settings).
`COALEX_ENDPOINT`	No	`https://traces.azure.coalex.ai`	Coalex proxy endpoint URL. Set to `http://localhost:8080` for local development.
`COALEX_SERVICE_NAME`	No	`coalex-sdk-python` / `coalex-sdk-typescript`	Service name for the OTLP resource attribute. Identifies your agent in traces.
`COALEX_LLM_PROVIDER`	No	`vertex`	Default LLM provider for examples: `vertex`, `openai`, or `anthropic`.
`COALEX_MODEL`	No	Provider default	Override the default model for the selected provider.

Usage in code¶

PythonTypeScript

import os
import coalex

coalex.register(
    endpoint=os.getenv("COALEX_ENDPOINT", "http://localhost:8080"),
    api_key=os.environ["COALEX_API_KEY"],
    service_name=os.getenv("COALEX_SERVICE_NAME", "my-agent"),
)

import { register } from "@coalex-ai/sdk";

register({
    endpoint: process.env.COALEX_ENDPOINT ?? "http://localhost:8080",
    apiKey: process.env.COALEX_API_KEY!,
    serviceName: process.env.COALEX_SERVICE_NAME ?? "my-agent",
});

Local development

For local development with docker compose up:

export COALEX_API_KEY="ck_live_..."       # from admin dashboard
export COALEX_ENDPOINT="http://localhost:8080"

Infrastructure Variables¶

These variables configure the backend services deployed to GCP Cloud Run.

Proxy¶

Variable	Required	Default	Description
`AUTH_SERVICE_URL`	Yes	--	Internal URL of the auth service (e.g., `http://coalex-auth:8081`).
`COLLECTOR_URL`	Yes	--	Internal URL of the OTel collector (e.g., `http://coalex-collector:4318`).
`COALEX_GCS_BUCKET`	No	--	GCS bucket name for static asset serving.

Collector¶

Variable	Required	Default	Description
`PUBSUB_PROJECT`	Yes	--	GCP project ID for Pub/Sub.
`PUBSUB_TOPIC`	Yes	--	Pub/Sub topic name for span export.

Transformer¶

Variable	Required	Default	Description
`DUCKLAKE_POSTGRES_URI`	Yes	--	PostgreSQL connection URI for DuckLake catalog (e.g., `postgresql://coalex:coalex@localhost:5432/ducklake`).
`PUBSUB_PROJECT`	Yes	--	GCP project ID for Pub/Sub subscription.
`PUBSUB_TOPIC`	Yes	--	Pub/Sub topic name to subscribe to.

GCP¶

Variable	Required	Default	Description
`COALEX_PROJECT_ID`	Yes	--	GCP project ID for deployment.
`GCP_REGION`	No	`europe-west1`	GCP region for Cloud Run deployments.

Publishing Variables¶

These variables are used by the CI/CD pipeline for SDK publishing.

Variable	Required	Context	SDK	Description
`PYPI_TOKEN`	Yes (publish)	GitHub Actions secret	Python	PyPI API token for publishing the Python SDK (`coalex`).
`NPM_TOKEN`	Yes (publish)	GitHub Actions secret	TypeScript	npm token for publishing the TypeScript SDK (`@coalex-ai/sdk`).

LLM Provider Credentials¶

These variables are required by the example agents and any code using the respective LLM providers.

Vertex AI (Google)¶

Variable	Required	Description
`GOOGLE_CLOUD_PROJECT`	Yes	GCP project ID with Vertex AI enabled.

Application Default Credentials

Vertex AI uses Application Default Credentials instead of an API key:

gcloud auth application-default login

OpenAI¶

Variable	Required	Description
`OPENAI_API_KEY`	Yes	OpenAI API key (starts with `sk-`).

Anthropic¶

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Anthropic API key (starts with `sk-ant-`).

AWS Bedrock¶

Variable	Required	Description
`AWS_ACCESS_KEY_ID`	Yes	AWS access key for Bedrock.
`AWS_SECRET_ACCESS_KEY`	Yes	AWS secret key for Bedrock.
`AWS_DEFAULT_REGION`	No	AWS region (e.g., `us-east-1`).

Local Development Reference¶

A complete .env file for local development:

# Coalex SDK
COALEX_API_KEY=ck_live_your_key_here
COALEX_ENDPOINT=http://localhost:8080
COALEX_SERVICE_NAME=my-agent

# LLM Provider (choose one)
COALEX_LLM_PROVIDER=vertex
GOOGLE_CLOUD_PROJECT=your-project
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

# Infrastructure (set by docker compose)
# AUTH_SERVICE_URL=http://coalex-auth:8081
# COLLECTOR_URL=http://coalex-collector:4318
# DUCKLAKE_POSTGRES_URI=postgresql://coalex:coalex@postgres:5432/ducklake
# PUBSUB_PROJECT=coalex-ai
# PUBSUB_TOPIC=coalex-spans

Warning

Do not commit .env files to source control. The monorepo's .gitignore already excludes them.