# Environment Variables

<details>

<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

* [.gitignore](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/.gitignore/README.md)
* [docs/PRDS/126-BUSINESS-KNOWLEDGE-GRAPH.md](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/docs/PRDS/126-BUSINESS-KNOWLEDGE-GRAPH.md)
* [graphify-out/snapshots/bucket-1-pre-drop.sql](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/graphify-out/snapshots/bucket-1-pre-drop.sql)
* [orchestrator/.env.example](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/.env.example)
* [orchestrator/alembic/versions/prd135\_drop\_bucket\_1.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/alembic/versions/prd135_drop_bucket_1.py)
* [orchestrator/core/credentials/service.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/core/credentials/service.py)
* [orchestrator/core/models/credentials.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/core/models/credentials.py)
* [orchestrator/core/services/plugin\_cache.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/core/services/plugin_cache.py)

</details>

This document describes the environment variable configuration system used across all Automatos AI services. Environment variables control database connections, external service credentials, feature flags, and service-specific settings across the 19-service production topology.

For deployment infrastructure, see [Production Deployment](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/20.6). For credential management in the UI, see [Credentials Management](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/17.5).

***

## Overview

Automatos AI uses environment variables for all external configuration to support multiple deployment targets (Docker Compose, Railway, Kubernetes) without code changes. Variables are loaded from `.env` files in local development and from platform-provided environment in production.

The system follows a three-tier loading strategy:

1. **Environment variables** (highest priority) — set by hosting platform or shell.
2. **`.env` file** — loaded via `python-dotenv` in the backend application lifecycle.
3. **Hardcoded defaults** — fallback values in centralized config.

The codebase includes an service-specific `orchestrator/.env.example` for the core API and a global `.gitignore` that protects sensitive environment files.

**Sources:** [orchestrator/.env.example:1-65](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md), [.gitignore:102-109](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## Environment Variable Loading Flow

The following diagram illustrates how configuration flows from environment sources into the core system entities.

**Diagram: Configuration Injection Pipeline**

```mermaid
graph TB
    subgraph "Environment_Sources"
        EnvFile[".env file"]
        ComposeEnv["docker-compose.yml<br/>environment section"]
        PlatformEnv["Platform Environment<br/>(Railway/Cloud)"]
    end
    
    subgraph "Code_Entity_Config_Manager"
        ConfigModule["config.py<br/>(Centralized Config)"]
    end
    
    EnvFile --> ConfigModule
    ComposeEnv --> ConfigModule
    PlatformEnv --> ConfigModule
    
    subgraph "System_Consumers"
        DB["Database Services<br/>SQLAlchemy / pgvector"]
        RedisSvc["RedisClient<br/>(core/redis/client.py)"]
        LLM["LLMManager<br/>(API Providers)"]
        Auth["Auth Service<br/>(Clerk JWT)"]
        PluginSvc["PluginContentCache<br/>(core/services/plugin_cache.py)"]
        WorkspaceWorker["WorkspaceWorker<br/>(services/workspace-worker)"]
    end
    
    ConfigModule --> DB
    ConfigModule --> RedisSvc
    ConfigModule --> LLM
    ConfigModule --> Auth
    ConfigModule --> PluginSvc
    ConfigModule --> WorkspaceWorker
```

**Sources:** [orchestrator/core/services/plugin\_cache.py:42-47](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md), [orchestrator/.env.example:1-65](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## Required Environment Variables

These variables **must** be set for the system to function. Missing required variables will cause startup failures in production.

### Core Infrastructure

| Variable            | Purpose                     | Example                    | Used By                         |
| ------------------- | --------------------------- | -------------------------- | ------------------------------- |
| `POSTGRES_PASSWORD` | PostgreSQL admin password   | `secure_db_pass_123`       | `pgvector` container, `backend` |
| `REDIS_PASSWORD`    | Redis authentication        | `secure_redis_pass`        | `redis` container, `backend`    |
| `API_KEY`           | Internal API authentication | `your_secure_api_key_here` | `backend`                       |
| `API_HOST`          | Host binding for the API    | `0.0.0.0`                  | `backend`                       |
| `API_PORT`          | Port binding for the API    | `8000`                     | `backend`                       |

**Sources:** [orchestrator/.env.example:6,11,14-16](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## Database and Cache Configuration

### PostgreSQL with pgvector

The system uses `pgvector` for semantic search and `orchestrator_db` for relational data.

| Variable        | Default           | Purpose                    |
| --------------- | ----------------- | -------------------------- |
| `POSTGRES_HOST` | `localhost`       | PostgreSQL server hostname |
| `POSTGRES_PORT` | `5432`            | PostgreSQL port            |
| `POSTGRES_DB`   | `orchestrator_db` | Database name              |
| `POSTGRES_USER` | `postgres`        | Database user              |

**Sources:** [orchestrator/.env.example:1-5](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

### Redis Configuration

Redis serves as the L1 memory tier, Pub/Sub broker, and task queue.

| Variable     | Default     | Purpose               |
| ------------ | ----------- | --------------------- |
| `REDIS_HOST` | `localhost` | Redis server hostname |
| `REDIS_PORT` | `6379`      | Redis port            |

**Sources:** [orchestrator/.env.example:9-11](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## LLM Provider Configuration

Automatos AI supports a multi-provider strategy. While variables can be set in the environment, the system also supports a dynamic **Credential Store** for per-workspace keys managed by `CredentialStore`.

**Diagram: LLM API Key Resolution**

```mermaid
graph TD
    subgraph "Request_Context"
        Req["Agent Execution Request"]
    end

    subgraph "Resolution_Logic_CredentialStore"
        Store["CredentialStore.get_credential()<br/>(core/credentials/service.py)"]
        Env["os.getenv('OPENAI_API_KEY', ...)"]
    end

    Req --> Store
    Store -- "Not Found" --> Env
    Env -- "Found" --> Provider["LLM Provider Client<br/>(OpenAI/Anthropic/Gemini)"]
    Store -- "Found (Encrypted)" --> Decrypt["EncryptionService.decrypt_dict()<br/>(core/credentials/encryption.py)"]
    Decrypt --> Provider
```

| Variable            | Purpose                           |
| ------------------- | --------------------------------- |
| `OPENAI_API_KEY`    | Key for OpenAI models             |
| `ANTHROPIC_API_KEY` | Key for Anthropic models          |
| `LLM_PROVIDER`      | Default provider (e.g., `openai`) |
| `LLM_MODEL`         | Default model (e.g., `gpt-4`)     |
| `LLM_MAX_TOKENS`    | Token limit per request           |
| `LLM_TEMPERATURE`   | Default model temperature         |

**Encryption:** Credentials stored in the database are encrypted using `encryption_service.encrypt_dict()` before being persisted in the `credentials` table [orchestrator/core/credentials/service.py:146-150](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md). The `Credential` model stores this as `encrypted_data` [orchestrator/core/models/credentials.py:74](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md).

**Sources:** [orchestrator/.env.example:18-26](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md), [orchestrator/core/credentials/service.py:146-150](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md), [orchestrator/core/models/credentials.py:60-75](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## Service-Specific Configuration

### Plugin and Marketplace

Controls the marketplace caching and storage.

| Variable                    | Purpose                          | Default                   |
| --------------------------- | -------------------------------- | ------------------------- |
| `PLUGIN_CACHE_TTL_SECONDS`  | TTL for Redis plugin cache       | `3600`                    |
| `MARKETPLACE_S3_BUCKET`     | S3 bucket for plugin storage     | `automatos-marketplace`   |
| `PLUGIN_MAX_UPLOAD_SIZE_MB` | Max size for plugin uploads      | `10`                      |
| `PLUGIN_LLM_SCAN_MODEL`     | Model used for security scanning | `claude-haiku-4-20250414` |

**Sources:** [orchestrator/core/services/plugin\_cache.py:43-47](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md), [orchestrator/.env.example:48-54](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

### Universal Router and Webhooks

| Variable                           | Purpose                                   | Default |
| ---------------------------------- | ----------------------------------------- | ------- |
| `COMPOSIO_WEBHOOK_SECRET`          | Secret to validate incoming tool webhooks | (none)  |
| `ROUTING_CACHE_TTL_HOURS`          | TTL for routing decisions in Redis        | `24`    |
| `ROUTING_LLM_CONFIDENCE_THRESHOLD` | Threshold for Tier 3 routing              | `0.5`   |

**Sources:** [orchestrator/.env.example:38-40](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

### AWS and Cloud Integration

Used for S3-backed storage and PRD-42 Cloud Document Sync.

| Variable                | Purpose                      |
| ----------------------- | ---------------------------- |
| `AWS_ACCESS_KEY_ID`     | AWS authentication ID        |
| `AWS_SECRET_ACCESS_KEY` | AWS authentication secret    |
| `AWS_REGION`            | Target AWS region            |
| `S3_VECTORS_ENABLED`    | Toggle for cloud vector sync |

**Sources:** [orchestrator/.env.example:49-51,61-64](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***

## System and Logging

| Variable       | Purpose                                              | Default                 |
| -------------- | ---------------------------------------------------- | ----------------------- |
| `ENVIRONMENT`  | Deployment stage (`development`, `production`)       | `production`            |
| `LOG_LEVEL`    | Verbosity of backend logs (`DEBUG`, `INFO`, `ERROR`) | `INFO`                  |
| `LOG_FILE`     | Path to log output                                   | `logs/orchestrator.log` |
| `DEBUG`        | Toggle for FastAPI debug mode                        | `false`                 |
| `REQUIRE_AUTH` | Toggle for authentication enforcement                | `false` (local dev)     |

**Sources:** [orchestrator/.env.example:29-30,33,57-58](/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md)

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.automatos.app/automatos-ai-docs/design-docs/deployment-infrastructure/environment-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.