Configuration

ACOG is configured with environment variables, set through the chart’s infra.secret (secrets) and services.<service>.extraEnv (everything else). Each service reads its environment once at start, so a change takes effect after a restart (helm upgrade restarts what changed).

Secrets you generate

Variable	Generate with	Notes
ACOG_CREDS_KEY	openssl rand -base64 32	Encrypts every stored provider credential, two-factor secrets, SSO client secrets and the DLP dictionary key. The control plane and data plane must have the same value. If it is lost or changed, every stored credential must be entered again.
ACOG_OPERATOR_TOKEN	openssl rand -hex 32	Authenticates internal calls between services. If empty, DLP still enforces but records nothing.
ACOG_INGEST_TOKEN	openssl rand -hex 32	Authenticates usage records sent to metering. Metering will not start without it in production mode.
ACOG_POSTGRES_DSN		The PostgreSQL connection string
ACOG_CLICKHOUSE_PASSWORD		Must match the ClickHouse password

Control plane

Variable	Set to	Why
ACOG_ENVIRONMENT	production	The default, development, writes account-recovery links to the log instead of mailing them. Production mode requires an email relay and marks the session cookie Secure, so the console must be served over HTTPS. Set it on metering too.
ACOG_SELF_SERVE_SIGNUP	false	Public sign-up is on by default
ACOG_WEB_ORIGIN, ACOG_PUBLIC_BASE_URL	https://acog.example.com	Your console’s real address. Email links, SSO redirects and passkeys are built from it.
ACOG_TRUSTED_PROXY_CIDRS	Your ingress and load-balancer networks	So per-key IP allowlists see the real client address
ACOG_BOOTSTRAP_ADMIN_EMAIL	The first administrator’s email	First install only; see Install on Kubernetes
ACOG_CLICKHOUSE_DATABASE	acog (already set)	Leave as is

Email

Variable	Notes
ACOG_EMAIL_PROVIDER	smtp or ses. In production the control plane refuses to start without one.
ACOG_EMAIL_FROM	The sender address
ACOG_SMTP_HOST, ACOG_SMTP_PORT	Port 587 uses STARTTLS. Set ACOG_SMTP_TLS only for implicit TLS on port 465.
ACOG_SMTP_USERNAME, ACOG_SMTP_PASSWORD	Put these in the infra Secret, not in a values file
ACOG_SES_REGION	For ses

Data plane

Variable	Default	Notes
ACOG_TRUSTED_PROXY_CIDRS		As for the control plane
ACOG_MAX_REQUEST_BYTES	67108864 (64 MiB)	Keep in step with the web tier’s body limit
ACOG_BATCH_HOLD_SECS	600	The longest batch wait served on the caller’s held connection; a longer one gets a job handle to poll. The connection is silent while held, so keep this at 600 or below: the web tier waits 660 s, as should your load balancer (see Install on Kubernetes). Otherwise held batches are cut off.
ACOG_RATE_LIMIT_ORG_PER_MIN	600	Default per-organization request limit; 0 disables
ACOG_RATE_LIMIT_KEY_PER_MIN	300	Default per-service-key request limit; 0 disables

Semantic cache

The semantic cache is off on a self-hosted installation until you add a vector store. You need all four of these:

infra:
  bundled:
    milvus:
      enabled: true
    minio:                              # a sibling of milvus, not inside it
      rootPassword: "<a real password>"
services:
  dataplane:
    extraEnv:
      ACOG_EMBEDDING_ENDPOINT: "http://aco-embedder:8086/embed"   # the full path
      ACOG_MILVUS_URL: "http://aco-milvus:19530"
corpusTenancy:
  semanticNameKeySecret:
    name: aco-semantic-cache-name-key

kubectl -n aco create secret generic aco-semantic-cache-name-key \
  --from-literal=ACOG_SEMANTIC_CACHE_NAME_KEY="$(openssl rand -hex 32)"

Milvus brings an etcd and a MinIO with it: three more Deployments and volumes (20, 5 and 20 GiB). Keep the naming key; a different key starts every organization’s cache empty again.

Each organization then switches the cache on or off under Admin → Gateway settings.

Data loss prevention

The chart runs the DLP service and a named-entity model for detecting names and medical terms. The DLP service reports ner_ready once the model is loaded; until then those two data types are unavailable and the console says so.

Keyless provider connections

To offer keyless connections, set the issuer address. See Install identity.

Variable	Notes
ACOG_WORKLOAD_IDENTITY_ISSUER_BASE	Your API’s public address plus /v1/identity. Unset means keyless connections are not offered.
ACOG_WORKLOAD_IDENTITY_KEY_SOURCE	local (default): signing keys are generated and stored sealed by ACOG_CREDS_KEY. kms: AWS KMS.
ACOG_WORKLOAD_IDENTITY_KEY_ROTATION	Default 2160h (90 days)
ACOG_WORKLOAD_IDENTITY_KEY_ACTIVATION_DELAY	Default 24h. If you upload key sets to Google or Anthropic by hand, allow days.