> ## Documentation Index > Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Environment variables, agent settings, and model configuration # Configuration Guide OmniCoreAgent supports configuration through environment variables, Python dictionaries, and specialized configuration objects. *** ## 1. Environment Variables Environment variables are the best way to manage sensitive data like API keys and connection strings. For the first working agent, set only `LLM_API_KEY`. Memory and events default to in-memory storage, workspace files default to local disk, and OmniServe settings have server-side defaults. Add backend variables only when you are intentionally moving from local defaults to persistent or cloud infrastructure. ### LLM API Key OmniCoreAgent uses one public environment variable for hosted model credentials: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export LLM_API_KEY=your_provider_key ``` Set `model_config["provider"]` to choose the provider. The runtime reads `LLM_API_KEY` and internally passes it to LiteLLM for the selected provider. Do not configure provider-specific key names in OmniCoreAgent examples. ### Optional Memory Backends The default memory backend is in-memory and needs no environment variables. Set these only when conversation history must live outside the current process. | Backend | Variable | Example | | ---------------- | -------------- | ------------------------------------------ | | **Redis** | `REDIS_URL` | `redis://localhost:6379/0` | | **SQL Database** | `DATABASE_URL` | `postgresql://user:pass@localhost:5432/db` | | **MongoDB** | `MONGODB_URI` | `mongodb://localhost:27017` | Optional MongoDB memory variables: | Variable | Purpose | | -------------------- | ---------------------------------------------------------- | | `MONGODB_DB_NAME` | MongoDB memory database name. Defaults to `omnicoreagent`. | | `MONGODB_COLLECTION` | MongoDB memory collection name. Defaults to `messages`. | ### Workspace Storage Workspace storage is separate from memory storage. Memory stores conversation history. Workspace storage stores files, scratchpads, artifacts, subagent outputs, and tool offloads. | Backend | Variables | | --------- | ------------------------------------------------------------------------------------------------------------------- | | **Local** | `OMNICOREAGENT_WORKSPACE_BACKEND=local`, `OMNICOREAGENT_WORKSPACE_DIR=./workspace` | | **S3** | `OMNICOREAGENT_WORKSPACE_BACKEND=s3`, `AWS_S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | | **R2** | `OMNICOREAGENT_WORKSPACE_BACKEND=r2`, `R2_BUCKET_NAME`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Optional workspace variables: | Variable | Purpose | | -------------------------------- | --------------------------------------- | | `OMNICOREAGENT_WORKSPACE_PREFIX` | Key prefix for S3/R2 workspace objects. | | `AWS_REGION` | AWS region for S3 workspaces. | | `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint. | ### Optional Telemetry Export Telemetry events and traces work in-process by default. Set exporter variables only when traces should leave the process for an OTLP-compatible backend. | Exporter | Variables | | ------------- | --------------------------------------------------------------------------------------------- | | **OTLP/HTTP** | `OTEL_EXPORTER_OTLP_ENDPOINT` or explicit exporter `endpoint` | | **LangSmith** | `LANGSMITH_API_KEY`, optional `LANGSMITH_PROJECT`, optional `LANGSMITH_OTEL_ENDPOINT` | | **Opik** | `OPIK_API_KEY`, `OPIK_WORKSPACE`, optional `OPIK_PROJECT_NAME`, optional `OPIK_OTEL_ENDPOINT` | Install the matching extra before exporting: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} pip install "omnicoreagent[otel]" pip install "omnicoreagent[langsmith]" pip install "omnicoreagent[opik]" ``` Python configuration can pass exporters directly: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import OmniCoreAgent agent = OmniCoreAgent( name="research-agent", system_instruction="You are a research assistant.", model_config={"provider": "openai", "model": "gpt-5.4-mini"}, telemetry_exporters=[ { "destination": "otlp", "endpoint": "http://localhost:4318/v1/traces", "service_name": "research-agent", } ], ) ``` ### OmniServe OmniServe reads these variables through `OmniServeConfig`. Environment variables override values passed in code. You do not need any OmniServe environment variables to start. Defaults bind the server to port `8000`, enable the background API, start the background worker, and use an in-memory task store. Set only the values you want to override. | Variable | Default | Purpose | | ------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- | | `OMNICOREAGENT_SERVE_HOST` | `0.0.0.0` | Server bind host. Must not be empty. | | `OMNICOREAGENT_SERVE_PORT` | `8000` | Server port. Must be `1`-`65535`. | | `OMNICOREAGENT_SERVE_WORKERS` | `1` | Direct OmniServe worker count. Must be `1`; run multiple processes behind a process manager for horizontal scaling. | | `OMNICOREAGENT_SERVE_API_PREFIX` | `""` | API route prefix, such as `/api/v1`. Normalized to a leading slash with no trailing slash; whitespace is invalid. | | `OMNICOREAGENT_SERVE_ENABLE_DOCS` | `true` | Enable Swagger UI. | | `OMNICOREAGENT_SERVE_ENABLE_REDOC` | `true` | Enable ReDoc. | | `OMNICOREAGENT_SERVE_CORS_ENABLED` | `true` | Enable CORS middleware. | | `OMNICOREAGENT_SERVE_CORS_ORIGINS` | `*` | Comma-separated allowed origins. | | `OMNICOREAGENT_SERVE_CORS_METHODS` | `*` | Comma-separated allowed methods. | | `OMNICOREAGENT_SERVE_CORS_HEADERS` | `*` | Comma-separated allowed headers. | | `OMNICOREAGENT_SERVE_CORS_CREDENTIALS` | `true` | Allow CORS credentials. | | `OMNICOREAGENT_SERVE_AUTH_ENABLED` | `false` | Enable Bearer token auth. Requires a non-empty `OMNICOREAGENT_SERVE_AUTH_TOKEN` value. | | `OMNICOREAGENT_SERVE_AUTH_TOKEN` | unset | Bearer token value used when auth is enabled. | | `OMNICOREAGENT_SERVE_REQUEST_LOGGING` | `true` | Log incoming requests. | | `OMNICOREAGENT_SERVE_LOG_LEVEL` | `INFO` | Server log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `TRACE`. | | `OMNICOREAGENT_SERVE_REQUEST_TIMEOUT` | `300` | Request timeout in seconds. Set `0` to disable timeout middleware. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED` | `false` | Enable in-process rate limiting. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS` | `100` | Requests per rate-limit window. Must be at least `1` when rate limiting is enabled. | | `OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW` | `60` | Rate-limit window in seconds. Must be at least `1` when rate limiting is enabled. | | `OMNICOREAGENT_BACKGROUND_ENABLED` | `true` | Expose background task endpoints. | | `OMNICOREAGENT_BACKGROUND_AGENT_ID` | `default` | Agent id used when OmniServe registers the served agent for background work. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE` | `in_memory` | Background control-plane store: `in_memory`, `sql`, `redis`, or `mongodb`. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URL` | unset | SQL or Redis URL. A URL with no backend selects SQL; use `OMNICOREAGENT_BACKGROUND_TASK_STORE=redis` for Redis URLs. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_URI` | unset | MongoDB URI. Setting this selects the MongoDB task store. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE` | `omnicoreagent` | MongoDB database name. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_PREFIX` | unset | Redis key prefix. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_COLLECTION_PREFIX` | unset | MongoDB collection prefix. | | `OMNICOREAGENT_BACKGROUND_TASK_STORE_CONNECT_TIMEOUT` | unset | Optional backend connect timeout in seconds. | | `OMNICOREAGENT_BACKGROUND_START_WORKER` | `true` | Start the scheduler and worker loop during server lifespan. | The background task store is separate from `MemoryRouter`. `MemoryRouter` stores conversation/session history. The task store stores scheduler/runtime state: tasks, schedule cursors, runs, attempts, leases, heartbeats, retries, and cancellation flags. Defaults are intentionally light. Use `sql`, `redis`, or `mongodb` when background tasks must survive process restarts. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. For Redis durability, enable Redis persistence and keep task-store keys out of eviction. MongoDB task-store writes use majority write concern. Durable background examples. Pick one backend: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Local SQLite durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=sql export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=sqlite:///.omnicoreagent/background.db ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Redis durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=redis export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=redis://localhost:6379/0 ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # MongoDB durability export OMNICOREAGENT_BACKGROUND_TASK_STORE=mongodb export OMNICOREAGENT_BACKGROUND_TASK_STORE_URI=mongodb://localhost:27017 export OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE=omnicoreagent ``` ## 2. Agent Configuration The `AgentConfig` handles the runtime behavior of the agent, such as reasoning steps and resource limits. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "tool_call_timeout": 30, # Max seconds per tool execution "max_steps": 15, # Max reasoning loops per run() "request_limit": 0, # 0 = unlimited "total_tokens_limit": 0, # 0 = unlimited "enable_subagents": True, # Dynamic focused workers "enable_workspace_files": True, # Default: workspace files for notes/logs/scratchpads "enable_agent_skills": True, # Enable local skill discovery "enable_advanced_tool_use": True, # Enable BM25 tool retrieval "context_management": {"enabled": True}, "tool_offload": {"enabled": True}, "governance_config": { "enabled": True, "profile": "interactive-dev", "sandbox_config": {"provider": "none"} } } agent = OmniCoreAgent( ... agent_config=agent_config ) ``` When `enable_subagents` is true, OmniCoreAgent automatically enables workspace files because spawned workers write output, todos, logs, and scratchpads into the active workspace. For full harness-style workloads, pair dynamic subagents with context management and tool offloading. Context management checks the prompt before each model call; tool offloading keeps large tool payloads in workspace artifacts instead of feeding the full payload back into the loop. `governance_config.sandbox_config` selects the sandbox runtime boundary used by governed execution. Supported built-in providers are: | Provider | Use | | ------------ | ---------------------------------------------------------------------------------------------- | | `none` | Policy-only mode. Does not satisfy `sandbox_required`. | | `local_test` | Development/test adapter that runs registered handlers only. No shell or production isolation. | Use `local_test` only for tests and local harness wiring: ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_config = { "governance_config": { "enabled": True, "sandbox_config": {"provider": "local_test"}, "allow_test_sandbox_runtime": True, } } ``` *** ## 3. Model Configuration The `model_config` defines which LLM to use and its sampling parameters. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} model_config = { "provider": "openai", "model": "gpt-4o", "temperature": 0.5, "max_tokens": 4000, "top_p": 0.9, } ``` Supported provider values are: `openai`, `anthropic`, `groq`, `ollama`, `azure`, `gemini`, `deepseek`, `mistral`, `openrouter`, and `cencori`. Provider-specific runtime options currently supported by OmniCoreAgent are: * Azure: `azure_endpoint`, `azure_api_version`, `azure_deployment` * Ollama: `ollama_host` *** ## 4. MCP Tool Configuration MCP tool servers are configured as a list of dictionaries. OmniCoreAgent only loads tools from MCP servers. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} mcp_tools = [ { "name": "explorer", "transport_type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }, { "name": "remote_service", "transport_type": "streamable_http", "url": "https://api.myapp.com/mcp", "headers": {"Authorization": "Bearer token"} } ] ``` *** ## 5. Persistence Configuration Pass a `MemoryRouter` to customize conversation memory. Runtime evidence is recorded through telemetry, which defaults to in-memory storage. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import MemoryRouter agent = OmniCoreAgent( ... memory_router=MemoryRouter("redis") ) ``` *** ## Best Practices * **Use `.env`**: Use a library like `python-dotenv` to load your environment variables during development. * **Model Selection**: Use smaller models (`gpt-4o-mini`) while building and testing your agent logic to save costs. * **Limit Steps**: Always set a reasonable `max_steps` to prevent the agent from entering infinite reasoning loops in case of tool failures.