Configuration

All configuration is environment variables. InsightWorker reads from (in order, first match wins):

<cwd>/.env (dev / per-project)
~/.insightworker/.env (installed default)
Process environment

Anything not set falls back to a sensible default. The full list:

LLM provider

You only need one. Auto-detection picks the first present provider when LLM_PROVIDER isn't set explicitly.

Variable	Default	Purpose
`LLM_PROVIDER`	auto	One of: `bedrock`, `anthropic`, `openai`, `azure`, `gemini`, `vertex`, `custom`.
`AGENT_NAME`	`InsightWorker`	Shown in banners and used in the agent's identity prompt.

AWS Bedrock (recommended for enterprise)

LLM_PROVIDER=bedrock
AWS_REGION=us-east-1
BEDROCK_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0
# Optional — falls back to ~/.aws/credentials or IAM role
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

# Hybrid routing for cost optimization
BEDROCK_MODEL_FAST=us.anthropic.claude-haiku-4-5-20251001-v1:0
BEDROCK_MODEL_STRONG=us.anthropic.claude-opus-4-1-20250805-v1:0

Anthropic API direct

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
AGENT_MODEL=claude-sonnet-4-5

OpenAI

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

Azure OpenAI

LLM_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_DEPLOYMENT=my-gpt-4o
AZURE_OPENAI_API_VERSION=2024-08-01-preview

Google Gemini (AI Studio)

LLM_PROVIDER=gemini
GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-2.0-flash-001

Google Vertex AI (GCP)

LLM_PROVIDER=vertex
GOOGLE_CLOUD_PROJECT=my-gcp-project
GOOGLE_CLOUD_LOCATION=us-central1
# Optional — falls back to ADC if unset
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
VERTEX_MODEL=gemini-2.0-flash-001

Custom (vLLM, Ollama, in-house GPU)

LLM_PROVIDER=custom
CUSTOM_LLM_BASE_URL=http://gpu-box.internal:8000/v1
CUSTOM_LLM_API_KEY=optional-if-not-required
CUSTOM_LLM_MODEL=meta-llama/Llama-3.1-70B-Instruct

Permissions

Variable	Default	Purpose
`AUTO_APPROVE_TOOLS`	`true`	Set to `false` to require interactive y/N before every `write_file`, `edit_file`, or `bash` call. Read-only tools always auto-approve.
`MAX_TOOL_OUTPUT_LENGTH`	per-model	Override the per-model output cap (chars). Default scales to ~10% of the active model's context window.

Workspace

Variable	Default	Purpose
`WORKSPACE_DIR`	`process.cwd()`	Where files get written and bash runs. Defaults to the directory you launched `insightworker` from.
`SKILLS_DIR`	`<install>/skills`	Bundled skills directory. Override to point at custom skills.

Tools — external integrations

These are all optional. The corresponding tools return a clear error if their env vars are missing.

Microsoft 365 (Outlook + SharePoint via Graph)

MS_GRAPH_TENANT_ID=
MS_GRAPH_CLIENT_ID=
MS_GRAPH_CLIENT_SECRET=
MS_GRAPH_DEFAULT_USER_ID=you@acme.com   # send-as default

# SharePoint default site (optional convenience)
SHAREPOINT_DEFAULT_SITE=acme.sharepoint.com:/sites/Underwriting

The same app registration powers both Outlook and SharePoint tools. Permissions to grant in Azure AD:

Mail.Read, Mail.Send (or Mail.ReadWrite if you want draft management)
Sites.Read.All (or Sites.Selected for per-site grants)

JIRA Cloud

JIRA_BASE_URL=https://acme.atlassian.net
JIRA_EMAIL=you@acme.com
JIRA_API_TOKEN=...   # id.atlassian.com/manage-profile/security/api-tokens

Perplexity Sonar (live web search)

PERPLEXITY_API_KEY=pplx-...
PERPLEXITY_MODEL=sonar-pro

Airflow (REST API)

AIRFLOW_BASE_URL=http://localhost:8080
AIRFLOW_USERNAME=airflow
AIRFLOW_PASSWORD=airflow

PostgreSQL

DB_HOST=localhost
DB_PORT=5432
DB_NAME=
DB_USER=
DB_PASSWORD=
DB_SSL=false

Oracle / ADW

ORACLE_CONNECT_STRING=adw-host:1521/service_high
ORACLE_USER=
ORACLE_PASSWORD=

AWS Textract (OCR)

TEXTRACT_REGION=us-east-1   # falls back to AWS_REGION

Slack / Telegram (channel adapters, gateway mode)

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
TELEGRAM_BOT_TOKEN=...

Okta SSO (gateway mode only)

OKTA_ISSUER=https://myorg.okta.com/oauth2/default
OKTA_CLIENT_ID=
OKTA_CLIENT_SECRET=
OKTA_SCOPES=openid,profile,email,groups
SESSION_SECRET=change-me-in-production

Where do these env vars actually come from?

Three places, in order of precedence:

Process environment at launch time. Run LLM_PROVIDER=openai insightworker and that wins.
<cwd>/.env if it exists. Useful for per-project overrides.
~/.insightworker/.env — created by the installer with sane defaults.

Any variable left blank or unset uses the in-code default.

Troubleshooting precedence

# Print the resolved settings (without exposing secrets)
insightworker -c "What LLM provider and model are you currently configured to use?"

The agent reads process.env, dotenv, and the settings module the same way at startup. Asking it directly is the fastest way to verify your configuration.

Source: docs/getting-started/configuration.md in the public repo. Open a PR with corrections.