---
title: Configuration Reference
description: Environment variables, AgentBuilder options, provider clients, channels, tools, and server runtime settings.
---

# Configuration Reference

Use this page when you need the exact environment variable or programmatic entry point for a TnsAI runtime. Values passed to constructors or builders take precedence over environment variables unless a linked API says otherwise.

## Before you start

- Install Java 21 and the TnsAI modules for the runtime you are configuring.
- Choose one LLM provider or prepare an `LLMClient` implementation programmatically.
- Keep credentials outside source control and inject them through your process environment or secret manager.

## Minimum working configuration

For a hosted provider, export its required credential before starting the application:

```bash
export OPENAI_API_KEY="replace-with-a-secret"
```

For a self-hosted OpenAI-compatible endpoint, add the matching base URL:

```bash
export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
```

Then construct the client and agent as shown in the [Quickstart](../start/quickstart.md). Constructor or builder arguments can replace these environment values when configuration is application-owned.

## LLM provider environment variables

API-key clients fail loudly when neither a constructor argument nor the required environment variable is present. Every client derived from `AbstractLLMClient` also accepts a base-URL override derived from its key name: for example, `ANTHROPIC_API_KEY` maps to `ANTHROPIC_BASE_URL`. The table calls out aliases and required companion values that do not follow that rule.

| Client | Required environment variables | Optional environment variables and notes |
| --- | --- | --- |
| OpenAI | `OPENAI_API_KEY` | `OPENAI_BASE_URL`, `OPENAI_ORG_ID` |
| Anthropic | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
| Gemini | `GEMINI_API_KEY` | `GEMINI_BASE_URL` |
| Mistral | `MISTRAL_API_KEY` | `MISTRAL_BASE_URL` |
| Groq | `GROQ_API_KEY` | `GROQ_BASE_URL` |
| Cohere | `COHERE_API_KEY` | `COHERE_BASE_URL` |
| Hugging Face | `HUGGINGFACE_API_KEY` | `HUGGINGFACE_BASE_URL`; `HUGGINGFACE_ENDPOINT` is an alias for a dedicated endpoint |
| OpenRouter | `OPENROUTER_API_KEY` | `OPENROUTER_BASE_URL`, `OPENROUTER_SITE_URL`, `OPENROUTER_SITE_NAME` |
| Azure OpenAI | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT_ID` | `AZURE_OPENAI_API_VERSION` (defaults to `2024-08-01-preview`) |
| MiniMax | `MINIMAX_API_KEY` | `MINIMAX_BASE_URL`, `MINIMAX_GROUP_ID` |
| ZhipuAI | `ZHIPUAI_API_KEY` | `ZHIPUAI_BASE_URL` |
| Cerebras | `CEREBRAS_API_KEY` | `CEREBRAS_BASE_URL` |
| NVIDIA NIM | `NVIDIA_API_KEY` | `NVIDIA_BASE_URL` |
| DeepInfra | `DEEPINFRA_API_KEY` | `DEEPINFRA_BASE_URL` |
| Fireworks AI | `FIREWORKS_API_KEY` | `FIREWORKS_BASE_URL` |
| Together AI | `TOGETHER_API_KEY` | `TOGETHER_BASE_URL` |
| xAI Grok | `XAI_API_KEY` | `XAI_BASE_URL` |
| IBM watsonx.ai | `WATSONX_API_KEY`, `WATSONX_PROJECT_ID` | `WATSONX_BASE_URL` |
| Vertex AI | `VERTEX_AI_API_KEY`, `VERTEX_AI_PROJECT_ID` | `VERTEX_AI_LOCATION` (defaults to `us-central1`), `VERTEX_AI_BASE_URL` |
| Replicate | `REPLICATE_API_KEY` | `REPLICATE_BASE_URL`; the framework deliberately uses `_API_KEY`, not Replicate's `_API_TOKEN` spelling |
| DeepSeek | `DEEPSEEK_API_KEY` | `DEEPSEEK_BASE_URL` |
| Perplexity | `PERPLEXITY_API_KEY` | `PERPLEXITY_BASE_URL` |
| Databricks | `DATABRICKS_API_KEY`, `DATABRICKS_BASE_URL` | — |
| Qwen Cloud / DashScope | `DASHSCOPE_API_KEY` | `DASHSCOPE_BASE_URL` |
| Tencent Hunyuan | `HUNYUAN_API_KEY` | `HUNYUAN_BASE_URL` |
| Yi | `YI_API_KEY` | `YI_BASE_URL` |
| LM Studio | — | `LMSTUDIO_BASE_URL`, `LMSTUDIO_API_KEY`; both are optional for a local server |
| llama.cpp server | — | `LLAMACPP_BASE_URL`, `LLAMACPP_API_KEY`; both are optional for a local server |
| vLLM | — | `VLLM_BASE_URL`, `VLLM_API_KEY`; the key is needed only when the endpoint requires authentication |
| Ollama | — | `OLLAMA_BASE_URL`, `OLLAMA_API_KEY`; both are optional for a local server |
| AWS Bedrock | Standard AWS SDK credential chain | `AWS_REGION` |

The framework module's [provider matrix](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-llm#environment-variable-matrix) is the source for provider-specific behavior. Its `ProviderEnvVarConsistencyTest` guards the framework README against `requireApiKey(...)` call sites; the Docs contract test separately guards this consolidated page.

For Vertex AI, a non-default `VERTEX_AI_LOCATION` must be paired with a
matching regional `VERTEX_AI_BASE_URL`, such as
`https://europe-west4-aiplatform.googleapis.com`. The client reads the
location after deriving its default host, so setting only the location would
send the regional request path to the default `us-central1` hostname.

Databricks has no shared workspace endpoint. Always provide
`DATABRICKS_BASE_URL`; the constructor's placeholder URL is not a usable
service configuration.

## Channel environment variables

Slack, Discord, WhatsApp, and Email configuration records can also be supplied programmatically. Their `fromEnvironment()` factories return an empty result when a required group is incomplete, so treat every value in the Required column as a unit. Telegram accepts its token through the adapter constructor or `TELEGRAM_BOT_TOKEN`.

| Channel | Required environment variables | Optional environment variables |
| --- | --- | --- |
| Telegram | `TELEGRAM_BOT_TOKEN` | — |
| Slack Socket Mode | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_WEB_API_BASE_URL` |
| Discord Gateway | `DISCORD_BOT_TOKEN` | `DISCORD_APPLICATION_ID`, `DISCORD_REST_BASE_URL`, `DISCORD_INTENTS` |
| WhatsApp Cloud API | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_APP_SECRET` | `WHATSAPP_GRAPH_BASE_URL`, `WHATSAPP_WEBHOOK_PORT`, `WHATSAPP_WEBHOOK_PATH`, `WHATSAPP_WEBHOOK_BIND_ADDRESS` |
| Email | `EMAIL_IMAP_HOST`, `EMAIL_IMAP_USER`, `EMAIL_IMAP_PASSWORD`, `EMAIL_SMTP_HOST` | `EMAIL_IMAP_PORT`, `EMAIL_IMAP_SSL`, `EMAIL_IMAP_FOLDER`, `EMAIL_SMTP_PORT`, `EMAIL_SMTP_USER`, `EMAIL_SMTP_PASSWORD`, `EMAIL_SMTP_STARTTLS`, `EMAIL_FROM_ADDRESS`, `EMAIL_SENDER_ALLOWLIST`, `EMAIL_POLL_INTERVAL_SECONDS` |

## Built-in tool environment variables

Common tool configuration is intentionally separate from provider and channel credentials:

| Area | Environment variables |
| --- | --- |
| Search | `BRAVE_API_KEY`, `TAVILY_API_KEY` |
| Webhook messaging | `SLACK_WEBHOOK_URL`, `DISCORD_WEBHOOK_URL` |
| HTTP private-network opt-in | `TNSAI_HTTP_ALLOW_PRIVATE=1` |
| File guard | `TNSAI_FILE_SANDBOX_ROOT`, `TNSAI_FILE_ALLOWED_EXTS`, `TNSAI_FILE_MAX_READ_BYTES`, `TNSAI_FILE_MAX_WRITE_BYTES` |

See the [tool catalog](../capabilities/tools/catalog.md) for credentials owned by individual integrations.

## AgentBuilder options

`AgentBuilder` is the programmatic entry point for an agent. The current public surface is grouped below; the [Javadoc](https://javadoc.io/doc/dev.tnsai/tnsai-core/latest/com/tnsai/agents/AgentBuilder.html) has parameter and validation details.

- **Metadata and lifecycle** — `id`, `description`, `version`, `autoStart`, `idleTimeoutMs`, `tenantId`, `did`, `groupMembership`
- **Model and conversation** — `llm`, `communication`, `promptStrategy`, `promptStrategies`, `promptEnhancer`, `maxContextTokens`
- **Identity and accountability** — `identity`, `identities`, `principal`, `liabilitySink`, `authorityScope`, `paymentBroker`
- **Roles, plans, and recovery** — `role`, `roles`, `plan`, `plans`, `errorRecoveryScenario`, `errorRecoveryScenarios`, `plannerHandle`, `reasoningStrategy`
- **Memory and retrieval** — `memoryStore`, `memoryConfig`, `addKnowledgeSource`, `knowledgeSources`, `retrieval`, `chatKnowledge`, `liveChatKnowledge`
- **Skills and tools** — `skillStore`, `skillResolver`, `skillResolverPolicy`, `maxActiveSkills`, `actionExecutor`, `toolPojos`, `builtInTools`, `dynamicTool`, `dynamicTools`, `toolCallFilter`
- **Reliability and validation** — `idempotencyStore`, `relaxValidation`, `withReachabilityChecks`, `reachabilityCheckTimeout`, `validateFully`
- **Entry and terminal operations** — `create`, `build`

The builder does not expose per-call `temperature`, `topP`, or `maxTokens` setters. Configure those on the selected LLM client. For retrieval, add one or more `KnowledgeSourceConfig` values and a `RetrievalConfig`.

## Server configuration

The standalone server accepts CLI arguments and environment variables. CLI values win where both forms exist.

| Setting | CLI | Environment | Default or requirement |
| --- | --- | --- | --- |
| Port | `--port <number>` | `TNSAI_PORT` | `7777` |
| Bind address | `--host <address>` | `TNSAI_HOST` | `127.0.0.1` |
| Public bind opt-in | `--allow-public` | `TNSAI_ALLOW_PUBLIC` (`true`) | Required for non-loopback binds |
| Idle shutdown | `--idle-timeout <minutes>` | `TNSAI_IDLE_TIMEOUT` | `30` minutes |
| Bearer authentication | — | `TNSAI_TOKEN` | Mandatory when public binding is enabled; otherwise authentication is disabled when absent |
| Default model | — | `TNSAI_MODEL` | `glm-5:cloud` for the Ollama fallback |
| Provider selector | — | `TNSAI_PROVIDER` | The built-in environment fallback recognizes `ollama`; cloud providers require an SPI provider on the classpath |
| Provider key | — | `TNSAI_API_KEY` | Must be present to activate the environment provider path; the built-in `ollama` case currently ignores the value |
| Browser origins | — | `TNSAI_ALLOWED_ORIGINS` | Comma-separated additions to the origin policy |
| Workspace roots | — | `TNSAI_WORKSPACE_ROOT` | Platform path-separator-delimited; defaults to the current directory |
| Workspace scan limit | — | `TNSAI_WORKSPACE_MAX_FILES` | Overrides the workspace file limit |
| Audit output | — | `TNS_AUDIT_DIR` | Defaults to `./var/audit` |

For an embedded server, configure `TnsServer`, `BindPolicy`, `AuthConfig`, `OriginPolicy`, and `WorkspaceConfig` programmatically. There is no `server.yml` loader. YAML belongs only to the separate [declarative lifecycle-hook registry](../server/advanced.md), where applications explicitly parse hook definitions and register them.

## Per-agent LLM overrides

The variables above configure a provider process-wide. To override a *single agent's* provider, model or tuning without recompiling, register an `LLMConfigurationSource` on the SCOP bridge. Its `environment()` implementation reads:

```
TNSAI_LLM_<AGENT>_<FIELD>
```

`<AGENT>` is the agent name upper-cased with every non-alphanumeric character replaced by `_`; `<FIELD>` is one of `PROVIDER`, `MODEL`, `TEMPERATURE`, `MAX_TOKENS`, `ENDPOINT`, `API_KEY_ENV`. A `Researcher` agent's model comes from `TNSAI_LLM_RESEARCHER_MODEL`. Names differing only in punctuation collide after normalisation.

System properties are checked before environment variables and both are read on every call. A `.env` file is loaded once per JVM, so editing it — including removing an override — needs a restart.

`apiKeyEnv` can name any variable the process can see, and `endpoint` decides where that value is sent as a bearer token. Treat a configuration source as trusted infrastructure; see [External LLM Configuration](../capabilities/llm/configuration-sources.md).

## Related

- [Installation](../start/installation.md) — dependency and initial credential setup.
- [Server](../server/index.md) — standalone and embedded runtime behavior.
- [Help / FAQ](../help/faq.md) — common credential questions.
- [Troubleshooting](../help/troubleshooting.md) — missing credentials and connection failures.
- [External LLM Configuration](../capabilities/llm/configuration-sources.md) — per-agent overrides from a file or the environment.