Configuration Reference

Complete reference for all Thand Agent configuration options and their default values.

Table of Contents

1. Overview
2. Environment Configuration
   1. Basic Environment Settings
   2. Environment Config
      1. AWS-Specific Config
      2. GCP-Specific Config
      3. Azure-Specific Config
3. Server Configuration
   1. Basic Server Settings
   2. Server Limits
   3. Metrics Configuration
   4. Health Checks
   5. CORS Settings
4. Login Server Configuration
5. API Configuration
6. Logging Configuration
7. Services Configuration
   1. Encryption Service
   2. Vault Service
   3. Scheduler Service (Temporal)
   4. Temporal Configuration
   5. Large Language Model (LLM) Configuration
8. Roles Configuration
   1. External Role Loading
9. Workflows Configuration
10. Providers Configuration
11. Security Configuration
12. Environment Variables
    1. Examples
13. Configuration File Examples
    1. Minimal Configuration
    2. Complete Configuration
14. Validation

---

Overview

Thand Agent supports comprehensive configuration through YAML files, environment variables, and command-line flags. Configuration is loaded in the following order (later sources override earlier ones):

1. Default values (hardcoded)
2. Configuration file (config.yaml, ~/.config/thand/config.yaml, etc.)
3. Environment variables (prefixed with THAND_)
4. Command line flags

---

Environment Configuration

Core environment settings that define the runtime context and platform.

Basic Environment Settings

Option	Type	Default	Description
environment.name	string	Auto-detected	Name of the environment or hostname
environment.platform	string	aws	Platform type: aws, gcp, azure, kubernetes, local
environment.os	string	Auto-detected	Operating system: windows, darwin, linux
environment.os_version	string	Auto-detected	Operating system version
environment.arch	string	Auto-detected	System architecture: amd64, arm64
environment.ephemeral	boolean	false	Whether running in ephemeral environment

Environment Config

Platform-specific configuration settings:

Option	Type	Default	Description
environment.config.timeout	duration	5s	Timeout for config fetch operations
environment.config.key	string	changeme	Default encryption key name
environment.config.salt	string	changeme	Default encryption salt
environment.config.api_key	string	-	API key for environment operations

AWS-Specific Config

Option	Type	Default	Description
environment.config.profile	string	-	AWS profile to use
environment.config.region	string	-	AWS region
environment.config.access_key_id	string	-	AWS access key ID
environment.config.secret_access_key	string	-	AWS secret access key
environment.config.kms_arn	string	-	AWS KMS key ARN for encryption
environment.config.imsd_disable	boolean	-	Disable AWS instance metadata service

GCP-Specific Config

Option	Type	Default	Description
environment.config.project_id	string	-	GCP project ID
environment.config.location	string	-	GCP location/region
environment.config.key_ring	string	-	Cloud KMS key ring name
environment.config.key_name	string	-	Cloud KMS key name

Azure-Specific Config

Option	Type	Default	Description
environment.config.vault_url	string	-	Azure Key Vault URL

---

Server Configuration

Settings for the Thand server when running in server mode.

Basic Server Settings

Option	Type	Default	Description
server.host	string	0.0.0.0	Server bind address
server.port	integer	5225	Server listen port

Server Limits

Option	Type	Default	Description
server.limits.read_timeout	duration	30s	HTTP read timeout
server.limits.write_timeout	duration	30s	HTTP write timeout
server.limits.idle_timeout	duration	120s	HTTP idle timeout
server.limits.requests_per_minute	integer	100	Rate limit for requests per minute
server.limits.burst	integer	10	Rate limit burst size

Metrics Configuration

Option	Type	Default	Description
server.metrics.enabled	boolean	true	Enable Prometheus metrics endpoint
server.metrics.path	string	/metrics	Metrics endpoint path
server.metrics.namespace	string	thand	Metrics namespace prefix

Health Checks

Option	Type	Default	Description
server.health.enabled	boolean	true	Enable health check endpoint
server.health.path	string	/health	Health check endpoint path
server.ready.enabled	boolean	true	Enable readiness check endpoint
server.ready.path	string	/ready	Readiness check endpoint path

CORS Settings

Option	Type	Default	Description
server.security.cors.allowed_origins	[]string	["https://thand.io", "https://*.thand.io"]	Allowed CORS origins
server.security.cors.allowed_methods	[]string	["GET", "POST", "PUT", "DELETE", "OPTIONS"]	Allowed HTTP methods
server.security.cors.allowed_headers	[]string	["Authorization", "Content-Type", "X-Requested-With"]	Allowed headers
server.security.cors.max_age	integer	86400	CORS preflight cache duration (seconds)

---

Login Server Configuration

Settings for connecting to the Thand login server.

Option	Type	Default	Description
login.endpoint	string	https://login.thand.io	Login server endpoint URL
login.base	string	/	Base path for login endpoints
login.api_key	string	-	API key for login server authentication

---

API Configuration

Settings for the REST API.

Option	Type	Default	Description
api.version	string	v1	API version
api.rate_limit.requests_per_minute	integer	-	API-specific rate limit
api.rate_limit.burst	integer	-	API-specific burst limit

---

Logging Configuration

Control logging behavior and output format.

Option	Type	Default	Description
logging.level	string	info	Log level: trace, debug, info, warn, error, fatal, panic
logging.format	string	json	Log format: json, text
logging.output	string	stdout	Log output destination

---

Services Configuration

External service integrations and configurations.

Encryption Service

Option	Type	Default	Description
services.encryption.provider	string	local	Encryption provider: aws, gcp, azure, local
services.encryption.config.*	map	-	Provider-specific encryption config

Vault Service

Option	Type	Default	Description
services.vault.provider	string	local	Vault provider: aws, gcp, azure, local
services.vault.config.*	map	-	Provider-specific vault config

Scheduler Service (Temporal)

Option	Type	Default	Description
services.scheduler.provider	string	local	Scheduler provider
services.scheduler.config.*	map	-	Provider-specific scheduler config

Temporal Configuration

Option	Type	Default	Description
services.temporal.host	string	localhost	Temporal server host
services.temporal.port	integer	7233	Temporal server port
services.temporal.namespace	string	default	Temporal namespace
services.temporal.api_key	string	-	Temporal Cloud API key
services.temporal.mtls_cert	string	-	mTLS certificate content
services.temporal.mtls_cert_path	string	-	Path to mTLS certificate file

Large Language Model (LLM) Configuration

Option	Type	Default	Description
services.llm.provider	string	-	LLM provider: openai, gemini, anthropic
services.llm.api_key	string	-	API key for LLM provider
services.llm.base_url	string	-	Custom base URL for LLM API
services.llm.model	string	-	Model name (e.g., gpt-4, gemini-pro)

---

Roles Configuration

Define and load role definitions.

Option	Type	Default	Description
roles.path	string	./examples/roles	Local directory for role files
roles.url	object	-	Remote URL endpoint for roles
roles.vault	string	-	Vault secret path for roles
roles.*	map	-	Inline role definitions

External Role Loading

Roles can be loaded from external sources:

# Load from local directory
roles:
  path: "./config/roles"

# Load from remote URL
roles:
  url:
    uri: "https://example.com/roles.yaml"
    method: "GET"
    headers:
      Authorization: "Bearer token"

# Load from vault
roles:
  vault: "secret/roles"

---

Workflows Configuration

Define and load workflow definitions.

Option	Type	Default	Description
workflows.path	string	./examples/workflows	Local directory for workflow files
workflows.url	object	-	Remote URL endpoint for workflows
workflows.vault	string	-	Vault secret path for workflows
workflows.plugins.path	string	-	Local directory for workflow plugins
workflows.plugins.url	string	-	Remote URL for workflow plugins
workflows.*	map	-	Inline workflow definitions

---

Providers Configuration

Define and load provider configurations.

Option	Type	Default	Description
providers.path	string	./examples/providers	Local directory for provider files
providers.url	object	-	Remote URL endpoint for providers
providers.vault	string	-	Vault secret path for providers
providers.plugins.path	string	-	Local directory for provider plugins
providers.plugins.url	string	-	Remote URL for provider plugins
providers.*	map	-	Inline provider definitions

---

Security Configuration

Option	Type	Default	Description
secret	string	changeme	Secret key for signing cookies and tokens

---

Environment Variables

All configuration options can be set via environment variables using the THAND_ prefix and converting nested keys to uppercase with underscores:

Examples

# Environment settings
export THAND_ENVIRONMENT_PLATFORM="aws"
export THAND_ENVIRONMENT_CONFIG_REGION="us-west-2"

# Server settings
export THAND_SERVER_HOST="0.0.0.0"
export THAND_SERVER_PORT="8080"

# Logging
export THAND_LOGGING_LEVEL="debug"
export THAND_LOGGING_FORMAT="json"

# Services
export THAND_SERVICES_LLM_PROVIDER="openai"
export THAND_SERVICES_LLM_API_KEY="sk-..."
export THAND_SERVICES_LLM_MODEL="gpt-4"

# Temporal
export THAND_SERVICES_TEMPORAL_HOST="temporal.example.com"
export THAND_SERVICES_TEMPORAL_NAMESPACE="production"

# External sources
export THAND_ROLES_VAULT="secret/roles"
export THAND_WORKFLOWS_VAULT="secret/workflows"
export THAND_PROVIDERS_VAULT="secret/providers"

---

Configuration File Examples

Minimal Configuration

environment:
  name: "production"
  platform: "aws"

logging:
  level: "info"
  format: "json"

server:
  host: "0.0.0.0"
  port: 5225

Complete Configuration

# Environment configuration
environment:
  name: "production-agent"
  platform: "aws"
  config:
    region: "us-west-2"
    timeout: "10s"

# Server configuration
server:
  host: "0.0.0.0"
  port: 5225
  limits:
    read_timeout: "30s"
    write_timeout: "30s"
    requests_per_minute: 200
  metrics:
    enabled: true
    namespace: "thand-prod"
  security:
    cors:
      allowed_origins: ["https://app.example.com"]

# Login server
login:
  endpoint: "https://auth.example.com"
  api_key: "${LOGIN_API_KEY}"

# Services
services:
  llm:
    provider: "openai"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4"
  
  temporal:
    host: "temporal.example.com"
    port: 7233
    namespace: "production"
    api_key: "${TEMPORAL_API_KEY}"

  vault:
    provider: "aws"
    config:
      region: "us-west-2"

# Logging
logging:
  level: "info"
  format: "json"

# External sources
roles:
  vault: "secret/production/roles"

workflows:
  vault: "secret/production/workflows"

providers:
  vault: "secret/production/providers"

# Security
secret: "${THAND_SECRET}"

---

Validation

Configuration validation occurs at startup. Common validation rules include:

• Required fields must be present
• Enum values must match allowed options
• Duration fields must be valid Go duration strings
• URL fields must be valid URLs
• Port numbers must be in valid range (1-65535)

Invalid configurations will cause the agent to fail startup with descriptive error messages.