Configuration

How OpenAgentic is configured — model provider, .env / Helm bootstrap, and the setup wizard.

OpenAgentic is configured in two layers: a bootstrap layer that you set once at install time, and a runtime layer that you manage from the admin console while the stack is running.

The bootstrap layer is a .env file for Docker Compose, or a values.yaml file for Helm. It sets the datastores, the first admin account, the model provider that is seeded on first boot, and the published host port. Everything else — which MCP servers are enabled and their credentials, model routing, users, and governance — is runtime configuration that lives in the admin console. You set the bootstrap layer once at install; you tune the runtime layer while the stack runs, with no restarts.

On a one-liner install, the setup wizard writes the .env file for you. The wizard walks through the deploy target (Compose or Helm), the admin user, Ollama, the model provider, MCP selection, per-MCP authentication, a review screen, and launch. Editing .env by hand or filling in values.yaml is the manual equivalent; the wizard writes the same .env shape. The wizard is an Ink TUI and requires Node.js 20 or later.

Choose a model provider

OpenAgentic requires a chat model and an embedding model. You configure them from one of two sources:

• Local Ollama — the recommended default. Point at an Ollama host that has a tool-capable chat model and an embedding model. Free, offline, no API keys. Ollama is the default embedding provider (EMBEDDING_PROVIDER=ollama, nomic-embed-text) and the default bootstrap chat provider in the shipped compose.
• A cloud provider (optional). Use Vertex AI, OpenAI, Azure OpenAI, AWS Bedrock, or Anthropic with credentials.

Providers are pluggable. The wizard seeds exactly one provider on first boot — Ollama by default; you add more later from the admin console. There is no single hardcoded vendor.

Important: The chat model must be tool-capable. The agentic chat always attaches tools, so a model without tool support (for example, Ollama gemma3:1b) is rejected with a 400 ... does not support tools error. Use a tool-capable model. On Ollama, the recognized local families are qwen, llama, gpt-oss, and mistral; on Vertex AI, any Gemini model works. Capability is auto-probed at boot.

Local Ollama (recommended default)

This is the local-first path: install Ollama, pull two open-weight models, and run the whole platform free, offline, with no API keys. Set the host and the two models in .env:

OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_EMBED_MODEL=nomic-embed-text
# A tool-capable chat model so users can chat with no cloud keys.
OLLAMA_CHAT_MODEL=qwen2.5:7b

nomic-embed-text (approximately 270 MB, CPU-only) is the default embedding model and is always pulled into the stack. The --quick install auto-detects a tool-capable chat model already on the host. It probes qwen2.5, qwen3, gpt-oss, llama3.3, llama3.1, llama-3, mistral, and gemma in that order, and falls back to pulling qwen2.5:7b if it finds none.

Vertex AI

Vertex AI uses Gemini models for chat, text-embedding-005 for embeddings (768 dimensions), and Imagen for image generation. The current defaults are chat gemini-2.5-flash, embedding text-embedding-005, and image imagen-3.0-fast-generate-001. Chat is seeded on first boot from the BOOTSTRAP_PROVIDER_* contract; embeddings read the GCP_* block.

Vertex supports three authentication modes. The project preference is ADC.

• Application Default Credentials (recommended). Run gcloud auth application-default login and let Compose mount ~/.config/gcloud read-only into the container. The @google/genai SDK auto-discovers the ADC, so do not set GOOGLE_APPLICATION_CREDENTIALS in this mode — pointing it at a user ADC fails, because that variable is validated as a service-account JSON file. The --vertex install flag wires this mode automatically.
• API key. Set VERTEX_AI_API_KEY. The --vertex-key <key> install flag wires this mode.
• Service-account key. Mount a service-account JSON read-only and reference it with GOOGLE_APPLICATION_CREDENTIALS (for example /var/secrets/gcp/key.json).

EMBEDDING_PROVIDER=vertex-ai
GCP_PROJECT_ID=your-project
GCP_LOCATION=us-central1
GCP_EMBEDDING_MODEL=text-embedding-005
EMBEDDING_DIMENSIONS=768          # 768-dim vector schema.
DEFAULT_IMAGE_MODEL=imagen-3.0-fast-generate-001

# Chat is seeded on first boot.
BOOTSTRAP_PROVIDER_TYPE=vertex-ai
BOOTSTRAP_PROVIDER_CONFIG={"projectId":"your-project","location":"us-central1"}

# ADC mode (recommended): no key, no GOOGLE_APPLICATION_CREDENTIALS — the SDK
# auto-discovers the gcloud ADC that Compose mounts read-only.
# API-key mode: VERTEX_AI_API_KEY=...
# Service-account mode: GOOGLE_APPLICATION_CREDENTIALS=/var/secrets/gcp/key.json

Caution: Set EMBEDDING_DIMENSIONS=768 and GCP_EMBEDDING_MODEL=text-embedding-005, so that the configured dimension matches the 768-dimension vector schema. The API also enforces an explicit environment-variable allowlist, so every GCP_* and VERTEX_AI_* key must be present in the Compose service block. The shipped docker-compose.yml already includes them; if you add keys, add them to the service block or they never reach the container.

Note: A user ADC can require periodic re-authentication (gcloud auth application-default login) under an organization’s reauth policy. A service account avoids that, but the project preference for Vertex is ADC.

Other cloud providers

Set whatever keys you have. They are all optional, and the model registry is rebuilt from each provider’s SDK on load, so there is no curated model list to maintain. BOOTSTRAP_PROVIDER_TYPE also accepts aws-bedrock if you want Bedrock seeded as the default chat model on first boot.

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=...
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
GOOGLE_GENERATIVE_AI_API_KEY=...

.env bootstrap keys

The following keys matter on first boot. Anything left blank uses a sensible default.

Note: The seed admin is written on first boot only. Set ADMIN_USER_EMAIL and ADMIN_SEED_PASSWORD before you start the stack. Change them afterward from the admin console.

Caution: Set all five internal service secrets to stable, long random strings before first boot. If any service falls back to a generated ephemeral value, sessions are invalidated on every restart. Generate with openssl rand -hex 32 for each.

Authentication

Authentication defaults to local username and password, stored in Postgres. Local auth is always available. In the self-hosted build, only local authentication is supported.

AUTH_PROVIDER=local
LOCAL_LOGIN_ENABLED=true

Cloud MCP credentials

OpenAgentic is the self-hosted build. In the self-hosted build, cloud MCP servers (AWS, Azure, GCP) authenticate with static service-account credentials only. There is no IdP-based on-behalf-of (OBO) delegation in the self-hosted build; OBO is an enterprise feature.

Provide cloud credentials in one of two ways:

• Mounted host config files. Compose mounts ~/.aws, ~/.azure, ~/.config/gcloud, and ~/.kube read-only into the mcp-proxy container.
• Static environment variables. For example, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for AWS, an Azure service principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID), or a GCP service-account key referenced by GCP_CREDENTIALS_FILE / GCP_CREDENTIALS_JSON (with GCP_PROJECT_ID).

If no host config is present, the mcp-proxy falls back to env files under ~/.openagentic/cloud-secrets/ (aws.env, azure.env, gcp.env).

Deploy on Kubernetes with Helm

The same choices live in the chart’s values.yaml, alongside per-service image coordinates (image.registry, image.tag), a bootstrapProvider block, and an ingress block. The bundled bootstrap path seeds one cloud provider on first boot. The documented example is AWS Bedrock, which makes Claude on Bedrock the default chat and Flows model; embeddings stay on the in-cluster Ollama (nomic-embed-text, 768 dimensions). Supply the AWS credentials as secrets and never commit them:

bootstrapProvider:
  enabled: true
  name: aws-bedrock
  displayName: AWS Bedrock
  type: aws-bedrock
  chatModel: anthropic.claude-sonnet-4-6

secrets:
  awsAccessKeyId: ""        # Set in your overlay, or use a pod IAM role.
  awsSecretAccessKey: ""
  awsRegion: us-east-1

helm upgrade --install openagentic https://install.openagentics.io/openagentic-1.0.0.tgz \
  -n openagentic --create-namespace \
  -f your-values.yaml

Milvus is optional. By default the stack runs pgvector-only — a bare docker compose up -d boots healthy with no Milvus (MILVUS_ENABLED=false), and MCP tool and RAG embeddings live in the Postgres pgvector halfvec columns. Enable Milvus only for large embedding or RAG workloads: on Compose, run docker compose --profile milvus up -d with MILVUS_ENABLED=true and SKIP_TOOL_SEMANTIC_CACHE=false (or pass --milvus to the installer); on Helm, set milvus.enabled=true, which deploys Milvus with etcd and minio inline.

Caution: Keep the api at a single replica; never scale it past one. Two pods bounce model rediscovery off each other and neither becomes ready. The bundled datastores (postgres, milvus, ollama) use strategy: Recreate.

For the full overlay, see Kubernetes.

Runtime configuration in the admin console

After first boot, operational configuration lives in the admin console:

• MCP servers. Enable the first-party servers, paste credentials, and test the connection. The servers enabled by default are web, admin, aws, azure, gcp, kubernetes, github, prometheus, and loki. Add your own MCP servers here as well.
• Models and routing. Set the routing strategy (the SmartModelRouter selects a model per prompt), per-user model preferences, cost caps, and the model allowlist.
• Users and governance. Manage accounts and roles, and set permission- and group-based caps for Flows, cost budgets, and model allow/deny rules. The chat system prompt is RBAC-keyed (admin or member) and editable live.
• Memory. Set per-source toggles (chat, flows), retention, and whether memory auto-injects.
• Security. Configure DLP scanning, the human-in-the-loop tool-approval gate (mutating tool calls can require approval before they run), the read-only platform toggle, and the immutable audit trail. Audit logging of every tool call is always on.

Ports

Only the UI is published to the host, through UI_HOST_PORT (default 8080, mapped to container port 80). Every other service communicates over the internal network.

On Kubernetes, reach the UI with a port-forward:

kubectl -n openagentic port-forward svc/ui 8080:80

Important: Set the api ALLOWED_ORIGINS to the URL you reach the UI on (for example, http://localhost:8080). Otherwise, login and chat are blocked by CORS.

Status

OpenAgentic is at v1.0.0 and under active development. It is not FedRAMP authorized. Chat and Flows run end-to-end, including MCP tool execution.

What’s next

• Deploy on Kubernetes
• Configure MCP servers and credentials from the admin console after first boot.