Skip to content
Ankole

AppConfigure

For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/app-configuration/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.

In Console → AppConfigure, site administrators manage site defaults, workspace policies, and shared runtime parameters. Pod administrators use their existing Pod Settings permissions.

Find and scope a setting

Choose Site configuration and defaults or Current workspace overrides before editing. The page always names the data workspace. A site default affects workspaces without an override; it does not impose a maximum on workspace values.

By task is the default view. Related settings open one form with an operational summary. Read-only registry lists every registered key and pattern, its scope, value source, encryption, and management owner. Search reaches fields inside grouped forms and former key names, and opens the matching field. Named management links open the relevant Console page and tab.

Site keys use the stored site value and then the code default. Tenant keys resolve an explicitly consumed Agent override, the workspace override, the site default, then the code default. Pod keys use only the workspace value and the code default. Five supported Agent override keys have read-only Agent inspection; this does not create an Agent configuration editor.

Change and reset a setting

Edit one scope at a time, review the field’s units, and save. Grouped tasks commit together: a rejected field leaves the whole task unchanged and preserves the draft. Secrets stay masked unless explicitly revealed. Reset confirmation shows the current value, the actual fallback value, and its source. Reset removes an override even when it equals the fallback; manually saving the same number keeps an independent override.

Time fields offer readable units while preserving storage units. Output limits distinguish no explicit limit (null) from a numeric cap, and inactivity timeout controls explicitly support disabled (0). Reducing deletion retention shows the consequences before saving.

Trace and Control Plane Plugin changes retain a restart-required status until the serving process matches the saved settings. Brain’s background Tick checks the shared BM25 indexes every minute and rebuilds them when the tokenizer changes; maintenance may interrupt retrieval or block writes. Check the Brain health page and server Tick logs if repair fails.

The SMTP form can test the current draft without changing saved mail settings or creating an OTP. Omitting the password keeps the saved password. Test acceptance means transport acceptance; changing the draft invalidates its displayed test result.

AppConfigure and environment variables

AppConfigure stores declared product settings in PostgreSQL. Most changes affect subsequent work. Deployment environment variables provide bootstrap infrastructure, while custom tool credentials belong in Agent environment variables.

Current built-in AppConfigure keys

Ankole ships with the built-in AppConfigure keys listed below, and Control Plane Plugins can register additional keys. Treat the AppConfigure page in your running instance as the authoritative catalog.

Agent runtime

Key Scope Purpose
ai_agent.max_iterations Tenant Maximum model iterations for one Agent turn
ai_agent.max_output_tokens Tenant Output-token cap for one model response
ai_agent.inactivity_timeout_ms Tenant Time to wait for an inactive model or Provider before ending the turn
ai_agent.library.agent_plugin_defaults Tenant Default enablement for Agent Plugins
background_agent_jobs.max_running_per_agent Tenant Maximum concurrently running BackgroundAgentJobs per Agent; default 3, valid range 1–64
sessions.wake_recycle Tenant Cold-wake model conversation rotation thresholds (min_cold_gap_seconds: 3600, min_context_tokens: 128000, im_max_idle_seconds: 259200), rotating a cold large model conversation or multi-day idle external IM session onto a successor branch with a bounded <wake-briefing>

Pod, Base, Applet, and Drive

Key Scope Purpose
pod.allow_external_guests Tenant Allow invited external guests to access shared Pod pages; default true
pod.applet.limits Tenant Applet invocation limits (timeout_ms: 60000, heap_mb: 128)
pod.base.limits Tenant Base query and record limits (query_rows: 1000, record_bytes: 1000000, group_count: 1000, statement_timeout_ms: 5000)
pod.office.limits Tenant Office page limits across spreadsheets, Word documents, and presentations: the largest file an editor may open (max_file_bytes: 20971520) and when edits compact into the file (compaction_idle_seconds: 30, compaction_op_threshold: 100, compaction_structural_threshold: 10)
drive.trash_retention_days Tenant Days Ankole retains deleted Drive nodes before automatic purge; default 30, 0 keeps them indefinitely until changed
drive.vfs_max_upload_bytes Site Maximum bytes per Worker /drive VFS upload; default 0 uses the object-store upload limit
pod.ot_replay_window Tenant Number of recent document change batches retained for OT replay; default 1000
pod.ocr_existing_scans Tenant Send the scanned PDF pages that no OCR model read at upload to the OCR model; the OCR provider charges for every page; PDFs in the trash or inside a trashed folder are left out; default false

Workflows

Key Scope Purpose
workflow.max_concurrency_per_run Tenant Maximum task concurrency that one Workflow can request; default 8, valid range 1–32
workflow.max_running_per_agent Tenant Maximum running Workflow tasks across one Agent’s runs; default 8, valid range 1–64
workflow.max_agent_calls_per_run Tenant Maximum subagent calls that one Workflow can create; default 32, valid range 1–1,024

Updates to these keys apply to newly started Workflow work. An individual run may request a lower concurrency or subagent-call cap, but it cannot exceed the tenant limit. Read Workflows for task execution rules and other size bounds.

Brain

Brain model calls run as the tenant’s ankole_brain system Principal. Configure its extraction (light), analysis (heavy), URL fetching (web_fetch), and reranking (rerank) profiles in the Console model-profile editor. These profiles inherit Pod and site settings.

Key Scope Purpose
brain.enabled Tenant Enable Brain retrieval, learning, and maintenance; stored knowledge remains when disabled
brain.embedding_model Site Provider, model, and dimensions for vector retrieval; an empty value disables vector retrieval
brain.search_tokenizer Site BM25 tokenizer: icu, jieba, lindera_japanese, or lindera_korean; a change requires a BM25 index rebuild
brain.chunking Tenant Source chunk size, overlap, and input limits
brain.forgetting Tenant Decay half-lives for each memory kind
brain.dreaming_task_cron Tenant Schedule for regular knowledge consolidation
brain.self_healing_task_cron Tenant Schedule for rebuilding stale chunk, embedding, and search-index projections
brain.signal_channel_batch_idle_time Tenant Idle seconds before pending chat messages enter learning; conversation end also triggers learning
brain.skill_learning_enabled Tenant Enable Skill lesson learning and delivery; when disabled, stored lessons remain but are not supplied
brain.skill_learning_reflection_threshold Tenant Unconsumed Signal Jobs that one Agent must accumulate before Skill lesson reflection starts; minimum 2

Read Brain for knowledge behavior and model requirements, and Skill lessons for how Brain attaches learned guardrails to Skills.

AI Gateway and observability

Key Scope Purpose
ai_gateway.compaction Site Automatic conversation-history compaction policy
observability.traces.enabled Site Whether process-wide OpenTelemetry export starts on the next control-plane boot
observability.traces.provider Site Semantic projection for langfuse, langsmith, or generic opentelemetry traces
observability.traces.otlp_endpoint Site Base OTLP/HTTP endpoint for optional traces
observability.traces.otlp_headers Site Encrypted authentication headers for optional traces

See LLM observability for Langfuse, LangSmith, VictoriaTraces, and other OTLP/HTTP receivers.

Passwordless Email OTP and Pod login policy

Key Scope Purpose
authn.email.mail Site, encrypted SMTP mail transport (server, from, port, ssl, and optional credentials) for passwordless Email OTP sign-in; empty disables Email OTP
authn.email.code_ttl_seconds Site Verification-code lifetime in seconds; default 600
authn.email.send_limits Site Shared send window and maxima per email, source, and channel
authn.email.failure_limits Site Shared failure window and maxima per email and source
principals.pod_login_policy Tenant, managed elsewhere Pod member login and invitation policy (allow_email_otp, allow_member_credential_change, allowed_email_domains, require_sso_for_members, allow_invite_links); managed in Pod Settings

Identity, Plugins, feature flags, and tenant defaults

Key Scope Purpose
principals.identity_providers.active Tenant, read-only Active tenant Identity Providers that authenticate Pod workspace members and administrators; managed in Pod Settings and on the Identity Provider page
principals.identity_providers.directory_full_sync_interval_minutes Tenant Full organization-directory synchronization interval
tenants.privileged_tenant_id Site, read-only ID of the tenant whose siteadmin group administers this site
plugins.enabled_ids Site, managed elsewhere Optional (:optional) Control Plane Plugins to enable at the next start; :always plugins stay active with the build
features.<flag> Site Feature availability policy ({enabled, percent, targets}) backing OpenFeature (Ankole.Features.Config)
signals.show_dead_letter_error_details Site Whether dead-letter notices sent to Conversations include bounded, redacted Session turn error details; default false
system.timezone Tenant Default time zone for schedules and other control-plane features
i18n.default_locale Pod Default language for the interface, notifications, and Agent messages in this Pod; Pod administrators can also update it in Pod Settings

Workers, web reading, and security

Key Scope Purpose
agent_workers.ready_timeout_seconds Site Seconds that a Worker may stay not ready before it is rebuilt with a new cache disk; default 600 (10 minutes)
agent_workers.rendered_fetch_idle_ttl_ms Tenant Idle lifetime for the built-in web_fetch rendered fallback
security.ssrf_filter Site Whether model-controlled fetches reject private, loopback, link-local, and CGNAT addresses

Ankole rejects requests to cloud metadata addresses even when security.ssrf_filter is disabled.

agent_workers.ready_timeout_seconds governs how long the control plane waits on an observed unready Worker before rebuilding it, whereas idle Worker release is configured per provider via idleReleaseAfter in the WorkerProvider YAML; see Workers.

First-run state

Key Scope Purpose
setup.bootstrap_activation_code Site, read-only Temporary activation code for the first-run setup page
setup.completed Site, read-only Whether this instance has completed first-run setup

The first-run /setup flow manages both keys automatically. To read the activation code from the terminal, run kit show bootstrap-activation-code; never edit these keys on the AppConfigure page.

Encrypted settings

Ankole encrypts secret settings at rest and displays a mask in both the list and editor. Saving the masked placeholder preserves the current value, whereas entering new text replaces it. Use Reveal only when you actively need to inspect the stored value, and never copy revealed credentials into chat threads, screenshots, or support tickets.