Skip to main content

Configuration Reference

Akritas resolves every serve option in this order:

  1. explicit CLI flag;
  2. AKRITAS_* environment variable;
  3. strict JSON service configuration;
  4. built-in default.

Select the service configuration with -config <path> or AKRITAS_CONFIG. The CLI selector wins when both are present. A complete version-controlled schema example is available at configs/akritas/server.example.json. The file must be a non-empty regular JSON file no larger than 1 MiB with "version": 1; unknown fields, trailing JSON, and unsupported versions fail startup. Relative paths use the process working directory unless the selected subsystem documents different semantics.

Service JSON fields use snake case. For example:

{
  "version": 1,
  "address": "127.0.0.1:8090",
  "base_url": "http://127.0.0.1:8080/v1",
  "system_instructions": "instructions/SYSTEM.md",
  "skills_dir": "skills",
  "notifications_config": "configs/akritas/notifications.local.json",
  "alert_sources_config": "configs/akritas/alerts.local.json",
  "alert_store": "data/audit/alerts.jsonl",
  "request_timeout": "10m"
}

The main configuration stores only the environment-variable names selected by upstream_api_key_env and api_key_env; notification and alert-source configurations likewise store secret variable names. Actual secret values remain in the process environment.

-system-instructions selects a non-empty regular UTF-8 file no larger than 64 KiB and defaults to instructions/SYSTEM.md. A relative path is resolved from the process working directory. The file is prepended to the first system message of every upstream request and is not reloaded while the process runs.

-skills-dir selects the operational skill catalog and defaults to skills. Set it to an empty string to disable skills. Immediate child directories are limited to 128 skills, each SKILL.md is limited to 64 KiB, total input is limited to 512 KiB, descriptions are limited to 512 bytes, and at most eight automatic or model-requested exact names enter a Run. When enabled, knowledge.list_skills returns metadata without instructions and knowledge.load_skill loads one exact name. Skill files are trusted configuration but cannot grant host capabilities; loading one is not evidence.

-response-language is a host-owned BCP 47 language tag for model-generated prose. It defaults to en and is independent of the language used by an API client or Web UI user. The interface and host-owned diagnostics remain English.

-notifications-config selects a separate strict JSON notification configuration and defaults to empty, which disables delivery. The same path is available through service field notifications_config and environment variable AKRITAS_NOTIFICATIONS_CONFIG. Receiver formats are documented in Notifications and Bots. The same file configures bidirectional bot ingress through inbound_mode, optional inbound_secret_env, conversation and user allowlists, and bounded bot_queue_size, bot_history_messages, bot_history_bytes, bot_session_ttl, and bot_max_sessions fields. Telegram supports polling and webhook; Mattermost supports webhook. Ingress secrets and bot tokens remain environment-only.

-alert-sources-config selects a separate strict version 1 source registry and defaults to empty, which disables provider-specific routes. Enabling it requires a non-empty -alert-store. The corresponding service fields are alert_sources_config and alert_store; environment variables are AKRITAS_ALERT_SOURCES_CONFIG and AKRITAS_ALERT_STORE. The registry accepts 1 to 32 generic, alertmanager, uptime-kuma, or pingdom sources with per-source authentication. See the Alert Sources Reference.

-public-url supplies the externally reachable base URL placed in notification Run links. It is also available as service field public_url and environment variable AKRITAS_PUBLIC_URL. Leave it empty when notification links should not be emitted.

The service configuration fields workspaces and change_validators are JSON string arrays. Their environment equivalents accept a JSON string array or comma-separated values. The first explicit repeatable -workspace or -change-validator flag replaces the configured list, and subsequent occurrences append. Workspace-catalog entries are then merged; duplicate names fail startup. Workspace validator_mode either appends workspace profiles or replaces the optional global list.

Startup is strict. Unknown JSON fields, trailing JSON, unsupported versions, invalid roots, duplicate profiles, unavailable validators, invalid MCP schemas, invalid or missing system instructions, invalid skill catalogs, invalid notification receiver or alert-source configs, invalid response-language tags, corrupt indexes or journals, upstream discovery errors, and corrupt audit history prevent the service from listening.

See Environment Variables for the complete JSON/environment/CLI mapping and the generated CLI Reference for every flag and default.