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 are the variables the Coalex SDKs read.

Variable	SDK	Default	Description
`COALEX_PROMPT_REFS`	Python, TypeScript	unset (on)	A vault prompt is exported as a reference to its version instead of its text, which makes traces smaller and keeps the same governance data. `0`, `false`, `no` or `off` turns it off and exports the text in full, as `register(prompt_refs=False)` (TypeScript: `register({ promptRefs: false })`) does. The argument to `register()` wins when both are set.
`COALEX_GENAI_SEMCONV`	Python	unset (off)	`1`, `true`, `yes` or `on` adds the OpenTelemetry GenAI message attributes to every span, as `register(genai_semconv=True)` does. The argument to `register()` wins when both are set.
`COALEX_SPOOL_DIR`	Python, TypeScript	`coalex` in the system temporary directory	Where `record_ungoverned()` keeps records that could not be delivered. Point it at a volume that survives a container restart.

The SDKs read no variable for the endpoint, the API key or the service name: pass them to register(). The next section shows an application reading its own variables and passing them on.

Variables the example agents use¶

These are conventions of the example agents in the repository, not variables the SDKs read.

Variable	Default	Description
`COALEX_API_KEY`	--	API key the example passes to `register()`. Generate it from the admin dashboard (Settings).
`COALEX_ENDPOINT`	`https://traces.coalex.ai`	Proxy URL the example passes to `register()`. Set to `http://localhost:8080` for local development.
`COALEX_SERVICE_NAME`	`coalex-sdk-python` / `coalex-sdk-typescript`	Service name the example passes to `register()`.
`COALEX_LLM_PROVIDER`	`vertex`	Default LLM provider for examples: `vertex`, `openai`, or `anthropic`.
`COALEX_MODEL`	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", "https://traces.coalex.ai"),
    api_key=os.environ["COALEX_API_KEY"],
    service_name=os.getenv("COALEX_SERVICE_NAME", "coalex-sdk-python"),
)

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

register({
    endpoint: process.env.COALEX_ENDPOINT ?? "https://traces.coalex.ai",
    apiKey: process.env.COALEX_API_KEY!,
    serviceName: process.env.COALEX_SERVICE_NAME ?? "coalex-sdk-typescript",
});

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.