Skip to main content

Running Akritas

Use akritas serve for the Web UI, native API, OpenAI-compatible facade, provider alert webhooks, read-only tools, changes, and Runs. Startup validates global model instructions, limits, workspace roots, validator profiles, MCP configuration, RAG index, alert sources, upstream model discovery, and journal history before listening.

Telegram and Mattermost can use the same native Chat loop. Telegram supports long polling without a public endpoint and webhook mode; Mattermost uses a provider-authenticated webhook endpoint. Connect them through AKRITAS_NOTIFICATIONS_CONFIG; setup, allowlists, bounded history, and commands are documented in Notifications and Bots.

For a system service or container, put non-secret settings in the versioned JSON service configuration and set AKRITAS_CONFIG to its mounted path. Every setting also has an AKRITAS_* override, and an explicit CLI flag has final precedence. The included Compose file therefore starts with only serve and loads its settings from .env. See the Configuration Reference.

The default global instructions are stored in instructions/SYSTEM.md. Select another file with -system-instructions /etc/akritas/SYSTEM.md. The selected file is loaded once and placed before task-specific system instructions for every upstream model call. Startup fails if it is missing, empty, invalid UTF-8, not a regular file, or larger than 64 KiB. The file is trusted operator configuration, but it cannot weaken host-side tool policy or validation.

Selective operational skills​

Place operational guidance in skills/<name>/SKILL.md. A file without front matter uses the directory name as its selector. Optional front matter supports an exact alias list:

---
name: postgresql
match:
  - postgres
  - postgresql
---
# PostgreSQL

After PostgreSQL is identified as the busy process, check active queries,
autovacuum, and waits when those read-only tools are available.

serve -skills-dir skills loads the catalog once at startup. Akritas selects a skill before planning when the latest request contains an explicit role, service, technology, component, database, db, engine, or platform field. It can select additional skills after successful inventory or CMDB checks. Free-form mentions and RAG documents do not trigger automatic selection.

If inventory is absent, fails, or cannot identify useful guidance, the planner or adaptive loop can call knowledge.list_skills to inspect names and short descriptions, then knowledge.load_skill with one exact catalog name. The list tool never returns instruction bodies; the load tool adds the selected instructions to the current Run system context and returns a confirmation. Aliases such as postgres remain useful for automatic matching but the load tool accepts only the canonical directory name. These calls consume the ordinary tool budget, and automatic plus requested loads share the limit of eight skills per Run. Loading a skill does not prove that the technology is installed or responsible for the incident.

Selected skill names appear in native chat and alert Runs and in the Web Run log. Skill guidance does not change the tool catalog, permissions, arguments, timeouts, or budgets.

The default address is 127.0.0.1:8090. Keep loopback for local operation. External exposure requires an inbound Bearer key and a trusted TLS/SSO proxy with rate limiting.

Set -response-language to a BCP 47 tag when model-generated prose should use a language other than the default en. For example, -response-language fr applies French to chat, alert investigation, and change-proposal text. It does not translate the Web UI or host-owned messages. The normalized tag is reported as response_language by /health and in the startup log.

Only one model generation runs at a time. Waiting requests share -request-timeout. /health remains unauthenticated for local and container health checks. Bot updates first enter a separate bounded queue and then use the same global generation slot. /health reports the number of enabled bidirectional receivers in bots, configured alert sources in alert_sources, and whether durable alert ingestion is enabled in alert_ingestion.

The model and tools count in the Web UI header is clickable. It opens the authenticated tool catalog with the name, read permission, and description of every tool admitted to the Web runtime. The same catalog is available from GET /api/v1/tools; it excludes denied tools, input schemas, and credentials.

After each chat request, the Web UI shows a Run log with the Run ID, actual tool calls, statuses, call IDs, investigation-plan status, and budget usage. The "Unavailable checks" section appears only when the host returns at least one capability_gaps item. An accepted plan with no unavailable checks is a normal status, not an error. Enable payload display before a request when raw plan arguments, tool arguments, and results are needed; these values can contain sensitive operational data.

Akritas forces the model to submit a structured investigation plan before the final answer. The planner can select only authorized read-only tools and sees their input schemas. The host validates and executes every accepted planned check, then supplies the results to the final model request. The remaining tool budget may be used for adaptive follow-up calls.

Each tool execution writes safe lifecycle records to stderr as component=akritas_tool event=start and event=finish. The records include the tool name, call ID, status, and duration, but omit arguments and results. The Web Run log also shows duration for every completed call. For a foreground WSL process, these records appear in the same terminal as akritas serve.