Environment Variables
Comprehensive reference for all environment variables used across Proxima Console components.
Loading order: environment variables > hardcoded defaults. All components (backend, agent, MCP server) are configured via environment variables only — there is no YAML config file.
How config is supplied in production (Kubernetes)
In the proxima-production cluster (namespace console-system), the backend's environment
comes from two places, both managed via GitOps in the argocd-infra repo:
- Non-secret defaults and endpoints are set as plain
envon the backend Rollout pod spec (e.g.PROXIMA_SERVER_BIND=0.0.0.0, the VictoriaMetrics/VictoriaLogs URLs below). - Secrets are injected by the External-Secrets Operator (ESO), which syncs them from the
in-cluster Vault (
vault.prxm.uz) into a Kubernetes Secret the pod loads viaenvFrom. No secret values appear in any manifest.
The variable names and meanings documented below are unchanged — only the source differs (pod
env + ESO-from-Vault in production, an .env file or shell in local dev). The
production endpoints they point at are called out in the relevant sections (
VictoriaMetrics, VictoriaLogs, OpenTelemetry,
Core). See Backend Deployment for the full topology.
Key production endpoints at a glance:
| Variable(s) | Production target |
|---|---|
PROXIMA_DB_URL | External managed psql01 — 10.10.3.11:30034 (PG 16, pgBackRest backups) |
VM_INSERT_URL / VM_SELECT_URL | In-cluster VM cluster via vmauth-proxy.monitoring:8427 |
VM_PROJECT_ID / VM_AUTH_USERNAME | 42 / vmuser-console (Console's isolated VM project + VMUser) |
PROXIMA_NATS_URL | nats://nats.prxm.uz:4222 — on the box (interim, moves to a dedicated VM) |
PROXIMA_VICTORIALOGS_URL | VictoriaLogs on the box (interim, moves to a dedicated VM) |
PROXIMA_OTEL_EXPORTER_ENDPOINT | Tempo on the box, :4317 (interim, moves to a dedicated VM) |
Backend
Core
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_DB_URL | — | Yes | PostgreSQL connection string. Format: postgres://user:pass@host:5432/dbname?sslmode=disable. Production: external managed psql01 at 10.10.3.11:30034 (PG 16). |
PROXIMA_NATS_URL | nats://localhost:4222 | No | NATS server URL. Production: nats://nats.prxm.uz:4222 — still on the box (interim, moves to a dedicated VM). |
PROXIMA_SERVER_PORT | 8080 | No | HTTP server listening port |
PROXIMA_SERVER_BIND | 127.0.0.1 | No | Address the HTTP server binds to. Production: set to 0.0.0.0 so kubelet probes and the in-cluster Service can reach :8080 (the istio gateway terminates TLS, not a same-host nginx). |
PROXIMA_LOG_LEVEL | info | No | Log level: debug, info, warn, error |
PROXIMA_CORS_ORIGINS | http://localhost:5173 | No | Comma-separated allowed CORS origins |
PROXIMA_GRPC_PORT | 0 (disabled) | No | gRPC server port for CLI terminal access. Defaults to 0, which disables the gRPC server — set a non-zero port to enable it. Production: TLS is terminated at the istio Gateway and gRPC traffic on api-console.prxm.uz:443 (HTTP/2) is routed to this port. |
PROXIMA_GRPC_BIND | 127.0.0.1 | No | Address the gRPC server binds to. Production: 0.0.0.0 so the Service can reach the gRPC port. |
PROXIMA_GRPC_TLS_CERT | — | No | Path to TLS certificate for gRPC server (empty = plaintext; in production the istio Gateway terminates TLS). |
PROXIMA_GRPC_TLS_KEY | — | No | Path to TLS private key for gRPC server |
Session Recording (Cloudflare R2)
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_R2_ENDPOINT | — | No | Cloudflare R2 S3-compatible endpoint URL. When empty, session recordings are disabled. |
PROXIMA_R2_BUCKET | — | No | R2 bucket name for storing session recordings |
PROXIMA_R2_ACCESS_KEY_ID | — | No | R2 access key ID |
PROXIMA_R2_SECRET_ACCESS_KEY | — | No | R2 secret access key |
PROXIMA_R2_REGION | auto | No | R2 region (typically auto for Cloudflare) |
Database Pool
| Variable | Default | Description |
|---|---|---|
PROXIMA_DB_MAX_OPEN_CONNS | 25 | Maximum number of open database connections |
PROXIMA_DB_MAX_IDLE_CONNS | 5 | Maximum number of idle connections in the pool |
PROXIMA_DB_CONN_MAX_LIFETIME | 300 | Connection maximum lifetime in seconds |
Authentication
| Variable | Default | Description |
|---|---|---|
PROXIMA_INSTALL_TOKEN | — | Shared install token for agent enrollment (development only). In production, use per-client install tokens via the API. |
PROXIMA_JWT_SECRET | — | JWT signing secret for access tokens. Required for JWT auth. |
PROXIMA_JWT_ACCESS_TTL | 900 | Access token TTL in seconds (default 15 minutes). |
PROXIMA_JWT_REFRESH_TTL | 604800 | Refresh token TTL in seconds (default 7 days). |
PROXIMA_VALKEY_URL | — | Valkey (Redis-compatible) URL for auth caches (lockout, MFA tokens, access resolution). |
WebAuthn (Passkeys)
Added in v0.4.5
Passkey authentication is disabled when PROXIMA_WEBAUTHN_RP_ID is not set. See Passkeys for setup details.
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_WEBAUTHN_RP_ID | — | For passkeys | Relying Party ID — the domain passkeys are bound to (e.g., app-console.prxm.uz). Must match the production domain exactly. |
PROXIMA_WEBAUTHN_RP_NAME | Proxima Console | No | Display name shown in browser/OS passkey dialogs. |
PROXIMA_WEBAUTHN_RP_ORIGINS | PROXIMA_FRONTEND_URL | No | Comma-separated list of allowed origins for WebAuthn ceremonies. |
PROXIMA_WEBAUTHN_CHALLENGE_TTL | 300 | No | Challenge expiry in seconds (default 5 minutes). Controls how long a user has to complete a passkey ceremony. |
AI Chat
Added in v0.5.0
AI Chat requires LiteLLM gateway and Vault Transit for message encryption. Chat is automatically disabled if either is unavailable.
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_LITELLM_URL | http://litellm:4000 | For AI chat | LiteLLM gateway URL |
PROXIMA_LITELLM_MASTER_KEY | — | For AI chat | LiteLLM admin API key |
PROXIMA_DEEPSEEK_API_KEY | — | For AI chat | Platform DeepSeek API key (standard tier) |
PROXIMA_KIMI_API_KEY | — | For AI chat | Platform Kimi/Moonshot API key (complex tier) |
PROXIMA_GOOGLE_API_KEY | — | For AI chat | Platform Google AI API key (expert tier) |
PROXIMA_CHAT_RATE_LIMIT | 30 | No | Chat messages per minute per user |
PROXIMA_CHAT_MAX_TOOL_CALLS | 10 | No | Max MCP tool calls per message (safety limit) |
PROXIMA_CHAT_MAX_CONVERSATION_MESSAGES | 100 | No | Soft limit on messages per conversation |
PROXIMA_CHAT_MAX_MESSAGE_LENGTH | 10000 | No | Maximum chat message length in characters |
PROXIMA_CHAT_CONTEXT_WINDOW | 50 | No | Max messages sent to LLM as context (sliding window) |
PROXIMA_CHAT_VAULT_KEK_NAME | proxima-chat-kek | No | Vault Transit key name for DEK encryption |
PROXIMA_MCP_BASE_URL | http://localhost:8081 | No | MCP server URL for tool execution |
NATS JWT
Added in v0.3.0
These variables configure NATS JWT/operator mode authentication and Vault Transit credential encryption. See NATS Security and Credentials for details.
| Variable | Default | Description |
|---|---|---|
PROXIMA_NATS_CREDS_FILE | — | Path to backend NATS credentials file |
PROXIMA_NATS_SYS_CREDS_FILE | — | Path to sys-admin NATS credentials file (for JWT revocation) |
PROXIMA_NATS_CA_FILE | — | Path to NATS TLS CA certificate |
VAULT_ADDR | — | Vault server address (for nkey seed storage and credential encryption via Transit) |
VAULT_TOKEN | — | Vault root token (from vault-init.sh output or infra/vault/.vault-keys) |
VAULT_ROLE_ID | — | Vault AppRole role ID (production — use instead of VAULT_TOKEN) |
VAULT_SECRET_ID | — | Vault AppRole secret ID (production — use instead of VAULT_TOKEN) |
Google OIDC SSO
| Variable | Default | Description |
|---|---|---|
PROXIMA_GOOGLE_CLIENT_ID | — | Google OAuth 2.0 client ID. When set (along with secret), the "Sign in with Google" button appears on the login page. |
PROXIMA_GOOGLE_CLIENT_SECRET | — | Google OAuth 2.0 client secret. |
PROXIMA_GOOGLE_ALLOWED_DOMAIN | proximaops.io | Google Workspace domain (hd) that SSO logins are restricted to; users outside it are rejected. Also gates auto-provisioning: when unset or empty, the backend will not auto-create or email-link accounts from a verified Google identity — SSO then succeeds only for accounts already explicitly linked by provider ID. Set it to enable safe open provisioning. |
PROXIMA_BACKEND_URL | http://localhost:8080 | Backend public URL, used to build OIDC redirect URIs. |
Google Groups RBAC
| Variable | Default | Description |
|---|---|---|
PROXIMA_GOOGLE_SERVICE_ACCOUNT_KEY | — | Path to Google service account JSON key file for Groups API. If unset, group sync is disabled. |
PROXIMA_GOOGLE_ADMIN_EMAIL | — | Google Workspace admin email for domain-wide delegation. Required if service account key is set. |
Server
| Variable | Default | Description |
|---|---|---|
PROXIMA_ENABLE_DEBUG_ENDPOINTS | true | Enable /swagger and /metrics debug endpoints. Set to false in production to hide these endpoints. |
Rate Limiting
| Variable | Default | Description |
|---|---|---|
PROXIMA_API_RATE_LIMIT | 1000 | Max API requests per minute per IP on all /api/v1/ routes. |
PROXIMA_AUTH_RATE_LIMIT | 5 | Max public auth requests per minute per IP (login, refresh, forgot-password, reset-password, accept-invite). Protected auth routes (sessions, me, mfa) use the general API limit. |
PROXIMA_CREDENTIAL_RATE_LIMIT | 10 | Max agent credential requests per minute per IP (/agents/enroll, /agents/credentials/renew, and /agents/credentials/renew/nonce). |
Admin Seeding
| Variable | Default | Description |
|---|---|---|
PROXIMA_ADMIN_EMAIL | — | Email for the initial super-admin user seeded at startup. Skipped if empty. |
PROXIMA_ADMIN_PASSWORD | — | Password for the initial super-admin user. Must meet the password policy (12+ characters). |
First Run
Set both variables on the first startup to create a super-admin account. The seed is idempotent — if a user with that email already exists, it is skipped. You can unset them after the first run.
MFA
| Variable | Default | Description |
|---|---|---|
PROXIMA_MFA_ENCRYPTION_KEY | — | Hex-encoded 32-byte AES-256 key for encrypting TOTP secrets at rest. |
Email
| Variable | Default | Description |
|---|---|---|
PROXIMA_EMAIL_PROVIDER | smtp | Email delivery provider: smtp or resend. |
PROXIMA_EMAIL_FROM | [email protected] | Sender email address. |
PROXIMA_EMAIL_FROM_NAME | Proxima Console | Sender display name. |
PROXIMA_RESEND_API_KEY | — | Resend API key (required when provider is resend). |
PROXIMA_SMTP_HOST | — | SMTP server hostname (required when provider is smtp). |
PROXIMA_SMTP_PORT | 587 | SMTP server port. |
PROXIMA_SMTP_USERNAME | — | SMTP authentication username. |
PROXIMA_SMTP_PASSWORD | — | SMTP authentication password. |
PROXIMA_FRONTEND_URL | https://app-console.prxm.uz | Frontend URL used in email links (password reset, invitations). |
Agent Liveness
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_STALE_TIMEOUT_SECONDS | 300 | Seconds without a heartbeat before marking an agent offline. Must be > 0. |
PROXIMA_AGENT_STALE_CHECK_SECONDS | 60 | Interval in seconds between stale-agent detection sweeps. Must be > 0. |
Validation
Both PROXIMA_AGENT_STALE_TIMEOUT_SECONDS and PROXIMA_AGENT_STALE_CHECK_SECONDS must be greater than 0, or the backend will fail to start.
Jira Integration (Feedback Widget)
| Variable | Default | Description |
|---|---|---|
PROXIMA_JIRA_BASE_URL | — | Atlassian instance URL (e.g. https://yourorg.atlassian.net). When empty, the feedback widget logs submissions to structured logs instead of creating Jira issues. |
PROXIMA_JIRA_EMAIL | — | Service account email for Jira API authentication (Basic Auth). |
PROXIMA_JIRA_API_TOKEN | — | Jira API token (paired with email for Basic Auth). |
PROXIMA_JIRA_PROJECT_KEY | — | Target Jira project key for feedback issues (e.g. PDD). |
PROXIMA_JIRA_ISSUE_TYPE | Task | Jira issue type name for created feedback issues. |
Compliance
| Variable | Default | Description |
|---|---|---|
PROXIMA_EXCEPTION_EXPIRY_CHECK_SECONDS | 300 | How often to check for expired compliance exceptions (seconds). Must be > 0. |
Runbook Rate Limiting
| Variable | Default | Description |
|---|---|---|
PROXIMA_RUNBOOK_RATE_LIMIT_PER_HOST | 5 | Max runbook executions per host per rate limit window |
PROXIMA_RUNBOOK_RATE_LIMIT_WINDOW_SEC | 600 | Rate limit window in seconds (default 10 minutes) |
ClickHouse (Service Desk)
Added in v0.5.0
ClickHouse is used as the read store for service desk ticket data. Required for the Service Desk feature.
| Variable | Default | Description |
|---|---|---|
PROXIMA_CLICKHOUSE_HOST | — | ClickHouse server hostname |
PROXIMA_CLICKHOUSE_PORT | 443 | ClickHouse HTTP port |
PROXIMA_CLICKHOUSE_USER | default | ClickHouse username |
PROXIMA_CLICKHOUSE_PASSWORD | — | ClickHouse password |
PROXIMA_CLICKHOUSE_TLS_SKIP_VERIFY | false | Skip TLS certificate verification for ClickHouse connection |
JSM (Service Desk Writes)
Added in v0.5.0
Jira Service Management API integration for service desk write operations (create tickets, add comments, transitions).
| Variable | Default | Description |
|---|---|---|
PROXIMA_JSM_BASE_URL | — | Jira Service Management REST API base URL |
PROXIMA_JSM_API_EMAIL | — | JSM API email for Basic auth |
PROXIMA_JSM_API_TOKEN | — | JSM API token |
PROXIMA_JSM_FIELD_CACHE_TTL | 24h | TTL for JSM field metadata cache (Go duration format) |
PROXIMA_JIRA_ORGANIZATION_ID | — | JSM organization ID for customer scoping |
PROXIMA_SERVICE_DESK_PENDING_TTL | 5m | TTL for pending write operations (Go duration format) |
VictoriaMetrics
Added in v0.2.0
These variables configure the connection to VictoriaMetrics Cluster for time-series metrics storage.
| Variable | Default | Description |
|---|---|---|
VM_INSERT_URL | http://localhost:8480 | vminsert endpoint for metrics ingestion. Production: the in-cluster VM cluster fronted by vmauth-proxy.monitoring:8427 (full path: vmauth-proxy.monitoring.svc.cluster.local:8427). |
VM_SELECT_URL | http://localhost:8481 | vmselect endpoint for metrics queries. Production: also vmauth-proxy.monitoring:8427. |
VM_WRITE_TIMEOUT | 10 | Write timeout in seconds |
VM_QUERY_TIMEOUT | 30 | Query timeout in seconds |
VM_PROJECT_ID | 0 (local dev) | Production: 42 — Console's isolated VM projectID. Combined with each client's per-tenant accountID, Console writes/reads tenant <accountID>:42, separate from the shared cluster's :0 tenants. |
VM_AUTH_USERNAME | — | Production: vmuser-console — the VMUser that vmauth-proxy authenticates Console as. |
VM_AUTH_PASSWORD | — | Password for the vmuser-console VMUser. Injected via ESO from Vault; never in manifests. |
Local dev vs production
In local dev the backend talks to the docker-compose VM cluster directly on :8480/:8481
with no auth and no project isolation. In production all metric reads and writes go through
vmauth-proxy:8427 authenticated as vmuser-console, scoped to projectID 42. See
VictoriaMetrics Architecture.
VictoriaLogs
Added in v0.3.0
Connection settings for VictoriaLogs (log ingestion and querying).
| Variable | Default | Description |
|---|---|---|
PROXIMA_VICTORIALOGS_URL | http://localhost:9428 | VictoriaLogs base URL for log ingestion and queries. Production: VictoriaLogs still on the box at :9428 (interim — firewalled to the cluster egress; moves to a dedicated VM in Phase L). |
OpenTelemetry
| Variable | Default | Description |
|---|---|---|
PROXIMA_OTEL_ENABLED | false | Enable OpenTelemetry distributed tracing |
PROXIMA_OTEL_EXPORTER_ENDPOINT | localhost:4317 | OTLP exporter endpoint (gRPC). Production: Tempo still on the box at :4317 (interim — firewalled to the cluster egress; moves to a dedicated VM in Phase L). |
PROXIMA_OTEL_SERVICE_NAME | proxima-backend | Service name for trace identification |
PROXIMA_OTEL_TRACES_SAMPLER | always_on | Trace sampler strategy |
PROXIMA_OTEL_TRACES_RATIO | 1.0 | Trace sampling ratio (0.0 to 1.0). Only used when sampler is traceidratio. |
Trace-ingest reuse
PROXIMA_OTEL_EXPORTER_ENDPOINT is also the endpoint the trace-ingest worker forwards agent spans to (agent spans arrive over NATS; the backend re-exports them to the same Tempo it sends its own spans to). The worker no-ops cleanly if this is unset. See Distributed Tracing.
Agent
Core
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_BACKEND_URL | — | Yes | Backend HTTPS URL for enrollment and renewal. |
PROXIMA_INSTALL_TOKEN | — | Yes (first run) | One-time install token for enrollment. Not needed after initial enrollment. |
PROXIMA_AGENT_TYPE | host | No | Agent type: host (full monitoring), k8s-node-monitor (kubelet metrics only), or collector (K8s API inventory). The Helm chart sets k8s-node-monitor for DaemonSet agents. |
PROXIMA_NATS_CA_FILE | — | No | Path to NATS TLS CA certificate (received during enrollment) |
PROXIMA_NATS_CREDS_FILE | — | No | Override path to NATS credentials file |
PROXIMA_LOG_LEVEL | info | No | Log level: debug, info, warn, error |
Enrollment
PROXIMA_BACKEND_URL and PROXIMA_INSTALL_TOKEN are required for the first run. The agent enrolls over HTTPS and receives NATS credentials, client/environment slugs, and the NATS URL from the backend. On subsequent runs, the agent loads credentials from disk and PROXIMA_INSTALL_TOKEN is no longer needed. See NATS Security.
Paths
Agent config is environment-only (since v0.6.0)
The agent no longer reads a YAML configuration file. It is configured purely via environment variables (plus built-in defaults); the former PROXIMA_AGENT_CONFIG / /etc/proxima-agent/config.yaml has been removed. Operational settings beyond startup are delivered as remote config from the backend over NATS.
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_DATA_DIR | /var/lib/proxima-agent | Directory for persistent agent data |
Intervals
All intervals are parsed as Go duration strings (e.g., 30s, 5m, 1h).
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_HEARTBEAT_INTERVAL | 30s | Heartbeat publish interval |
PROXIMA_AGENT_INVENTORY_INTERVAL | 15m | Full inventory snapshot interval |
PROXIMA_AGENT_METRICS_INTERVAL | 60s | Metrics collection interval |
PROXIMA_AGENT_PROCESS_INTERVAL | 30s | Process snapshot interval |
Resource Limits
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_MEMORY_LIMIT_MB | — (disabled) | Go soft memory limit via debug.SetMemoryLimit. Set to a positive integer to enable. |
PROXIMA_AGENT_COLLECTOR_TIMEOUT | 30s | Per-collector context deadline. Timed-out collectors degrade gracefully without blocking the agent. |
Distributed Tracing
The agent exports its spans to Tempo over NATS (no OTLP ingress needed). Tracing is off by default and the preferred control is the per-host tracing remote config (Agent config → Distributed tracing in the UI), which hot-reloads without a restart. The env vars below are an override for local/OTLP debugging. See Distributed Tracing.
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_OTEL_ENABLED | false | Override that forces NATS span export on (also flips the tracing block on), overriding the per-host UI config. Set to true or 1. |
PROXIMA_AGENT_OTEL_SAMPLE_RATIO | 0.1 | Head-sampling ratio for agent-root traces, applied via ParentBased(TraceIDRatioBased(ratio)). Float in [0,1]; invalid values are ignored with a warning. Also tunable from the UI. |
Labels
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_LABELS | — | Static labels as a JSON object. Example: {"team":"platform","env":"prod"} |
Labels from this variable are merged with any labels delivered via the agent's remote labels config (Agent config in the UI). On key conflict, the environment variable wins.
Auto-Discovery
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_AUTO_DISCOVER | false | Enable automatic service detection at startup. Set to true or 1 to enable. See Auto-Discovery. |
Integrations
| Variable | Default | Description |
|---|---|---|
PROXIMA_PG_DSN | — | PostgreSQL connection string for the PostgreSQL collector. Setting this automatically enables PostgreSQL metrics collection. Leave empty to disable. |
PROXIMA_DOCKER_SOCKET | /var/run/docker.sock | Path to the Docker Unix socket for the Docker collector. Setting this automatically enables Docker metrics collection. |
Log Collection
Added in v0.3.0
Agent-side log collection bootstrap settings. These environment variables set the initial log-collection config; richer settings (watched files, journald units) are delivered via the agent's remote log_collection config from the backend.
| Variable | Default | Description |
|---|---|---|
PROXIMA_AGENT_LOG_COLLECTION_ENABLED | false | Enable log collection (true or 1) |
PROXIMA_AGENT_LOG_INTERVAL | 10s | Log flush interval (Go duration format) |
Kubernetes
These variables apply to both the node agent (DaemonSet) and the cluster agent.
| Variable | Default | Description |
|---|---|---|
PROXIMA_K8S_NODE_METRICS | false | Enable kubelet/cAdvisor metrics collection (node agent only) |
PROXIMA_K8S_METRICS_INTERVAL | 30s | Kubelet scrape interval (node agent only) |
PROXIMA_K8S_NODE_NAME | (downward API) | Node name used as the agent enrollment name. Set via spec.nodeName in the DaemonSet for stable, idempotent re-enrollment. |
PROXIMA_CLUSTER_NAME | (required) | Cluster display name (cluster agent only). |
PROXIMA_CLUSTER_SLUG | (derived from name) | URL-safe cluster identifier used as the stable agent name for idempotent enrollment. Auto-derived from PROXIMA_CLUSTER_NAME if not set. |
PROXIMA_K8S_SYNC_INTERVAL | 5m | Full K8s inventory sync interval (cluster agent only). |
PROXIMA_K8S_HEARTBEAT_INTERVAL | 30s | Interval between liveness heartbeats published by the cluster agent. |
PROXIMA_K8S_POD_LIMIT | 5000 | Max pods per sync. When exceeded, non-Running pods are prioritized (cluster agent only). |
PROXIMA_K8S_EXCLUDE_NAMESPACES | (empty) | Comma-separated namespaces to exclude from collection (cluster agent only). |
MCP Server
Added in v0.5.0
The MCP server is a standalone service that exposes infrastructure data to LLM clients. See MCP Server Overview for details.
Core
| Variable | Default | Required | Description |
|---|---|---|---|
PROXIMA_API_URL | — | Yes | Proxima Backend base URL (shared with other components) |
PROXIMA_MCP_LISTEN_ADDR | :8081 | No | HTTP listen address |
PROXIMA_MCP_TRANSPORT | http | No | Transport: http (Streamable HTTP) or stdio |
PROXIMA_LOG_LEVEL | info | No | Log level: debug, info, warn, error (shared convention) |
PROXIMA_API_KEY | — | No | API key for stdio transport (injected into request context) |
TLS
| Variable | Default | Description |
|---|---|---|
PROXIMA_MCP_TLS_CERT | — | Path to TLS certificate file |
PROXIMA_MCP_TLS_KEY | — | Path to TLS private key file |
Auth & Limits
| Variable | Default | Description |
|---|---|---|
PROXIMA_MCP_AUTH_CACHE_TTL | 60s | Auth validation cache TTL (Go duration) |
PROXIMA_MCP_MAX_RESPONSE_TOKENS | 4000 | Hard cap on tokens per tool response. Must be > 0. |
OpenTelemetry
| Variable | Default | Description |
|---|---|---|
PROXIMA_MCP_OTEL_ENABLED | false | Enable OpenTelemetry distributed tracing |
PROXIMA_MCP_OTEL_ENDPOINT | localhost:4317 | OTLP gRPC exporter endpoint |
Frontend (Vite)
These variables are embedded at build time. Changes require a rebuild.
| Variable | Default (dev) | Default (prod) | Description |
|---|---|---|---|
VITE_API_BASE_URL | http://localhost:8080/api/v1 | https://api-console.prxm.uz/api/v1 | Backend API base URL |
Product Analytics (PostHog)
| Variable | Default | Required | Description |
|---|---|---|---|
VITE_POSTHOG_KEY | — | No | PostHog project API key. When empty, analytics are disabled. |
VITE_POSTHOG_HOST | — | No | PostHog instance URL (e.g. https://eu.posthog.com) |
VITE_POSTHOG_ENABLED | true | No | Set to false to disable analytics for self-hosted deployments |
Docker Compose (Development)
These variables configure the local development infrastructure in docker-compose.yml:
| Variable | Default | Service | Description |
|---|---|---|---|
PROXIMA_DB_USER | proxima | postgres | PostgreSQL username |
PROXIMA_DB_PASSWORD | proxima_dev | postgres | PostgreSQL password |
PROXIMA_DB_NAME | proxima | postgres | PostgreSQL database name |
PROXIMA_DB_PORT | 5432 | postgres | PostgreSQL port |
Example .env File
# Backend
PROXIMA_DB_URL=postgres://proxima:proxima_dev@localhost:5432/proxima?sslmode=disable
PROXIMA_NATS_URL=nats://localhost:4222
PROXIMA_SERVER_PORT=8080
PROXIMA_LOG_LEVEL=debug
PROXIMA_CORS_ORIGINS=http://localhost:5173
# NATS JWT credentials
PROXIMA_NATS_CREDS_FILE=infra/nats/creds/backend.creds
PROXIMA_NATS_SYS_CREDS_FILE=infra/nats/creds/sys-admin.creds
PROXIMA_NATS_CA_FILE=infra/nats/certs/ca.pem
# Vault (run `make vault-init` first, credentials saved to infra/vault/.vault-keys)
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=<from vault-init output or infra/vault/.vault-keys>
# For production, use AppRole instead:
# VAULT_ROLE_ID=<from vault-init output>
# VAULT_SECRET_ID=<from vault-init output>
# JWT Auth
PROXIMA_JWT_SECRET=your-secret-key
PROXIMA_VALKEY_URL=redis://localhost:6379
# Rate limits (requests per minute per IP)
PROXIMA_API_RATE_LIMIT=1000
PROXIMA_AUTH_RATE_LIMIT=5
PROXIMA_CREDENTIAL_RATE_LIMIT=10
# Admin seeding (first run only)
PROXIMA_ADMIN_EMAIL=[email protected]
PROXIMA_ADMIN_PASSWORD=change-me-on-first-login
# MFA (generate with: openssl rand -hex 32)
PROXIMA_MFA_ENCRYPTION_KEY=your-hex-encoded-32-byte-key
# Email
PROXIMA_EMAIL_PROVIDER=smtp
PROXIMA_SMTP_HOST=smtp.example.com
PROXIMA_SMTP_PORT=587
PROXIMA_SMTP_USERNAME=[email protected]
PROXIMA_SMTP_PASSWORD=smtp-password
PROXIMA_FRONTEND_URL=http://localhost:5173
# VictoriaMetrics
VM_INSERT_URL=http://localhost:8480
VM_SELECT_URL=http://localhost:8481
# OpenTelemetry (optional)
PROXIMA_OTEL_ENABLED=false
# MCP Server
PROXIMA_MCP_LISTEN_ADDR=:8081
PROXIMA_MCP_AUTH_CACHE_TTL=60s
PROXIMA_MCP_MAX_RESPONSE_TOKENS=4000
# Jira feedback integration (optional)
# PROXIMA_JIRA_BASE_URL=https://yourorg.atlassian.net
# [email protected]
# PROXIMA_JIRA_API_TOKEN=your-api-token
# PROXIMA_JIRA_PROJECT_KEY=PDD
See NATS Security for the full setup guide.