Aegis documentation

#AI — providers, models and the agent runtime

The AI module gives the platform an agent that knows it: an aegis agent with the manual as skills, a set of tools that act on the host, and a turn engine that runs a prompt to completion — streaming or not — from the command line or in the background.

Everything it knows lives in database/storage/ai/ai.db. This page describes the catalogue and the commands that manage it; the engine, the tools and the daemon are described as they land.

#Configuration

config/ai.toml is an area file: load_server() merges every config/*.toml, so the keys are available as config.get("ai.default_model").

toml
[ai]default_agent = "aegis"default_provider = "deepseek"default_model = "deepseek-flash"max_turns = 2max_steps = 25parallel_agents = 4parallel_tools = 4toolbox = trueshell_confirm = trueinteraction_timeout = 600request_timeout = 300[providers.deepseek]name = "DeepSeek"driver = "deepseek"auth_type = "bearer"api_url = "https://api.deepseek.com/v1"api_key = "sk-…"is_default = true[providers.xai]name = "xAI"driver = "xai"auth_type = "bearer"api_url = "https://api.x.ai/v1"api_key = "xai-…"
KeyMeaning
default_agentagent used when aegis ai prompt does not name one
default_provider, default_modelwhat an agent without a model runs on
max_turnsturns the background daemon runs at the same time
max_stepsprovider hops one turn may make
parallel_agents, parallel_toolsconcurrent sub-agents and tool calls
toolboxoffer the loading gate instead of every tool schema on every hop
shell_confirmask for a confirmation before a mutating tool runs
interaction_timeoutseconds a turn waits for an answer
request_timeoutseconds one provider request may take
compact_autofold the oldest messages before a turn reaches the window
compact_thresholdshare of the window that triggers the fold (0.80)
compact_keep_recentmessages always kept verbatim
compact_keep_tokenstokens of the tail the fold must not touch
compact_bufferroom kept free below the window
daemonrun the background daemon on this host

#Where the key comes from

Two places can hold a provider key, and the database wins:

  • ai_providers.api_key, written by aegis ai providers set-key;
  • config/ai.toml, the fallback for a provider whose row carries no key.
  • aegis ai providers list says which one is in use (key column reads db, config or missing) and masks the secret to its last four characters. A sync never writes a key: it keeps the one already in the row, so the config stays the fallback and set-key is the only way to override it.

    #Commands

    bash
    aegis ai providers listaegis ai providers show deepseekaegis ai providers syncaegis ai providers set-key deepseekaegis ai models listaegis ai models list --provider xaiaegis ai models sync

    providers sync writes both halves of the catalogue — every provider declared in config/ai.toml and every model declared in app/modules/ai/providers — and is safe to run again: nothing is deleted, and a model or provider disabled by hand keeps its state.

    A provider named in the config whose driver this build does not ship is reported as skipped instead of being guessed:

    text
    ⚠ sk-openai: no driver for that provider in this build

    --json prints the same listing as one object, for a script or the panel:

    bash
    aegis --json ai models list --provider deepseek

    #Tools

    A tool is a class with a ToolSpec in app/modules/ai/tools/builtin/; a sync mirrors the spec into ai_tools and the runtime resolves the handler from that registry by name. The row decides whether a tool is offered, never what it executes.

    PackToolsWhat it is for
    toolsexplore, searchfind and activate the other tools
    contextstatus, compacthow full the window is, and folding it
    aegisinfo, docs_search, docs_readthe host and the manual
    aegiscommand, services, tasksthe aegis command, the keeper, the tasker
    shellrun, pscommands and processes on this host
    filesread, list, search, write, editthe project tree
    chatinfo, list, history, searchthe transcripts in ai.db
    memoryremember, recall, list, get, update, forgetfacts kept between conversations
    todoadd, list, update, remove, clearthe checklist of this conversation
    skillslist, read, searchthe skill catalogue
    agentslist, callwho this agent may delegate to, and the call
    interactask, confirm, choosequestions the turn pauses on
    webfetchone public page, as text

    #Nothing is sent twice

    A turn sends tools.explore, tools.search and the few tools already activated — never the whole catalogue. tools.explore with no argument returns the index (each pack, its size, a few names); with a pack name it returns that pack and activates it. tools.search ranks the catalogue against a phrase like "run a linux command" and activates what matched. The engine offers the newly activated schemas from the next hop on.

    #Where a turn may write

    files.write and files.edit accept a path only inside /etc/aegis/storage/ai/data-generated. The code tree is read-only for a turn: a review, a recommendation, an inventory or a generated note goes there, and a setting is changed through the tool or the API that owns it — never by editing a rendered file, and never by editing config/*.toml while the platform has a model for that key.

    #Mutating tools

    shell.run, aegis.command, files.write and files.edit are marked is_mutator. With [ai] shell_confirm = true the engine asks for a confirmation through interact.confirm before running one. files.edit refuses a text run that appears more than once: an ambiguous edit is an error, not a guess.

    bash
    aegis ai tools listaegis ai tools list --pack shellaegis ai tools show files.readaegis ai tools disable shell.runaegis ai tools enable shell.runaegis ai tools sync

    tools sync upserts every declaration, keeps the status you set by hand and archives a tool whose module disappeared from the build.

    #Skills

    A skill is a prompt block an agent carries. The ones shipped with the platform live on disk:

    text
    storage/ai/skills/<category>/<skill>/skill.md

    skill.md starts with a TOML block between +++ lines — name, description, type, tags, version — and the rest is the text that goes into the system prompt. TOML instead of YAML because it is in the standard library.

    aegis ai skills sync imports them: a changed file updates its row, an unchanged one is left alone, a file that disappeared archives its row. A skill written from the command line has no file and sync never touches it.

    bash
    aegis ai skills listaegis ai skills show conventionsaegis ai skills add house-style --name "House style" --file notes.mdaegis ai skills edit house-style --file notes.mdaegis ai skills remove house-styleaegis ai skills sync

    The ten shipped skills are platform-overview (the two roots and every path), installation (how an archive becomes a running application), module-map (what each module owns), ai (chats, background turns, jobs, compaction and delegation), conventions (the rules every change follows), troubleshooting (the failures already seen), nginx (the vhost model and its options), php (versions, pools, sockets), bind (zones, records, types) and services (mail, postfix, dovecot, databases, certbot, FTP, queues). Each ships as a file, so editing one and running aegis ai setup is the whole change.

    #Delegation

    agents.call hands one task to an attached sub-agent. The tool cannot start a turn by itself, so it raises and the engine runs the child: a new chat linked to the parent (parent_chat_id, root_chat_id), a new turn with parent_turn_id, and the same loop with the sub-agent's own instructions, tools and model. Its final answer becomes the tool result.

    RuleWhy
    only agents in ai_agent_sub_agentsthe operator decides who may be called
    two levels deepa delegate that delegates forever is a fork bomb
    parallel = true runs children beside each otherindependent work should not queue
    max_parallel_agents caps itthe provider has its own concurrency limit

    A child's transcript stays in ai.db as its own chat, so the whole tree is readable afterwards: aegis ai jobs list shows the parent and the children, parent_turn_id links them.

    The shipped scout agent is a read-only investigator: docs, files, host facts and processes, no mutating tool. aegis delegates to it when a question is a self-contained lookup.

    #Memory

    ai_memories holds what a turn should not have to rediscover. A memory belongs to an agent (scope = 'agent'), to one chat, or to the host (global); the prompt carries the ten highest-ranked ones, one line each, and memory.recall searches the rest.

    ToolWhat it does
    memory.rememberkeep a fact, with its kind, tags and importance 0–5
    memory.recallsearch title, body and tags; a match records the use
    memory.listthe stored facts, best first
    memory.getone memory in full
    memory.updatecorrect a fact instead of storing a contradictory copy
    memory.forgetarchive one; the row stays for the audit

    Ranking is importance, then how often a memory was actually returned (hits), then recency — a fact nobody asks for sinks instead of crowding the prompt forever. The block is capped by count and by characters, so memory never eats the window.

    #Todos

    ai_todos is the checklist of one conversation: the steps the agent wrote before a multi-step job. The prompt carries the open ones and the operator sees them while the work runs. Nothing executes a todo — aegis.tasks is the tasker.

    ToolWhat it does
    todo.addappend a step
    todo.listthe plan as it stands
    todo.updatemark one active, done or cancelled
    todo.removedrop one
    todo.cleardelete the finished ones

    #Context and compaction

    Every hop reports its input tokens; the number is stored on the chat as context_tokens. Before a turn sends anything it compares that number with compact_threshold × context_window — 0.80 by default. When the line is crossed, the oldest messages are replaced by one summary stored on the chat and summary_until records the last message the summary covers. The transcript is never rewritten, so the rows stay readable after a fold.

    ToolWhat it does
    context.statusused tokens, window, percentage, whether a fold is due, how much a summary covers
    context.compactfolds the older messages; with a summary it applies it at once, without one the engine writes it

    A fold keeps the last compact_keep_recent messages verbatim, and the summary travels as a block in the system prompt, so a reload sees what the model saw.

    #Agents

    An agent is identity, instructions, loop limits, a model and what it attaches. The shipped one is a file:

    text
    storage/ai/agents/<slug>/agent.md

    The same +++ TOML block as a skill, with the agent fields; the body is the instructions that become the first block of the system prompt.

    FieldMeaning
    kindmaster, sub-agent or utility
    modelmodel slug the agent runs on
    max_stepsprovider hops one turn may make
    parallelmay it run sub-agents and tools concurrently
    max_parallel_agents, max_parallel_toolsthe two caps
    toolspack.* or one tool name
    skillscategory/* or one slug
    sub_agentsthe agents it may delegate to

    A system agent is owned by its file: a sync rewrites the row when the hash of the file changes, and reconciles its attachments — a tool dropped from agent.md is detached on the next sync. The command line refuses to edit or delete it; the file is where it changes.

    bash
    aegis ai agents listaegis ai agents show aegisaegis ai agents tools aegis --add shell.aegis ai agents skills aegis --add conventionsaegis ai agents add helper --name Helper --model deepseek-flashaegis ai agents subagents helper --add aegisaegis ai agents remove helper

    aegis is the system agent: it carries all four skills, every pack and the instructions that describe the platform, the manual, the tasker and the rules it must not break.

    #Setup

    bash
    aegis ai setupaegis ai setup --check

    setup writes the whole catalogue in the order the dependencies allow: providers, models, tools, skills, agents. It is safe after every deploy — all four syncs are upserts, a status set by hand survives, and a row whose file disappeared is archived rather than deleted. It does not start the daemon. One animated line says what it is doing while it works, then a summary line and the counts.

    --check asks every provider that has a key for its model list and reports whether the key works; the key itself is never printed.

    #Prompt and the turn engine

    bash
    aegis ai prompt "ce servicii sunt oprite?" --agent aegisaegis ai prompt --chat 629a26dc16ad4a8ea68240705cb60654 "și câte sunt în total?"aegis ai prompt "spune ok" --no-streamaegis ai prompt --json "spune ok"

    Without --chat the command opens a chat; the last line it prints is chat <uuid>, which is what continues the conversation next time. --agent picks the agent (the configured default otherwise), --model overrides the model for one chat, --max-steps caps the hops for one turn.

    --json prints one object with the final answer and nothing else; that mode sends a completion instead of a stream, because a stream would be written while it arrives. aegis --json ai prompt … does the same.

    prompt is a one-shot run, so the engine locks the interaction pack: the interact.* tools are not offered, a call to one is refused, and the prompt says the run cannot ask. Use aegis ai chat when a question is expected.

    #What a turn does

  • Resolve — chat → agent → model → provider → key. A missing step fails the
  • turn with a sentence that names it, before anything is spent.

  • Assemble the prompt — the agent's instructions, the skills it carries, the
  • summary of a folded window, and a runtime block (date, host, root, model).

  • Offer a few tools — tools.* and context.* always, plus whatever the
  • model activated earlier in this turn. That is why the model starts by exploring: a schema it never asked for is not in the request.

  • Hop — one provider call, streaming or not. The assistant message, the
  • usage and the cost are stored before the tools run, so a reload sees the turn while it is still going.

  • Run the tool calls — each gets a row in ai_tool_calls and a tool
  • message. A question (interact.*) is asked on the terminal and its answer becomes the tool result.

  • Finish — the turn row records steps, tools, tokens, cost and the status;
  • the chat goes back to idle.

    #Failures and limits

  • A transport error, a 429 or a 5xx is retried three times with a short backoff.
  • A 400, 401 or 404 fails at once with the provider's message.

  • The turn stops after max_steps hops and says so (status: max_steps).
  • Ctrl-C leaves the turn marked interrupted; the next run reads the same
  • transcript.

  • At compact_threshold (80% of the window) the oldest messages are folded into
  • a summary before the hop, and the turn continues from it.

    --json prints one object and nothing else:

    json
    {"ok": true, "chat": "…", "turn": 6, "status": "done", "content": "ok", "steps": 1, "tool_calls": 0, "input_tokens": 3937, "output_tokens": 2, "cost": 0.000592, "error": ""}

    #Chat

    bash
    aegis ai chataegis ai chat --chat <uuid>aegis ai chat --agent aegis --model deepseek-flash --no-stream

    A line in, a streamed answer out, a prompt again — no full-screen UI. While the model works, a small block at the bottom of the screen carries a spinner, the elapsed time and the tail of the reasoning (the last two paragraphs); when the answer starts, the block is erased and nothing of it is left behind — the full reasoning stays on the message. The answer is rendered as it arrives: headings and bullets lose their markers, inline code is coloured, and a fenced block is drawn with its language.

    A tool call prints one human line, never JSON:

    text
      · Run aegis status 574ms  · Explore tools 0ms  ✖ Fetch https://example.invalid 12ms — cannot fetch the page
    CommandWhat it does
    /helpthe command list
    /newstart a new chat on the same agent
    /sessionsthe last twenty chats, numbered
    /sessions <n>switch to one (number or UUID prefix)
    /chatthe UUID of this chat, for --chat or the panel
    /model [slug]show or change the model of this chat
    /contextused tokens, window, percentage
    /compactfold the older messages now, with a written summary
    /toolswhat this agent can call, grouped by pack
    /quitleave (Ctrl-D does the same)

    Ctrl-C during an answer interrupts the turn: the row is marked interrupted and the prompt comes back. The renderer lives in app/modules/ai/markdown.py and is the only place that turns Markdown into terminal styling, so an HTML view for the panel has one function to add rather than a second parser.

    #Background turns

    aegis ai prompt --background "…" queues the turn and returns immediately; the aegis-ai daemon claims it and runs it with the same engine. The daemon is a keeper service: an exclusive lock in run/ai.lock, a pid in run/ai.pid, a heartbeat in run/ai.heartbeat (90 s, restarted when it freezes), [ai] max_turns workers, and [ai] daemon = false to switch it off on a host that does not want it.

    CommandWhat it does
    aegis ai jobs listqueued and recent turns, with live counters
    aegis ai jobs show <id>one turn and the question it waits on
    aegis ai jobs cancel <id>drop a queued turn, or ask a running one to stop
    aegis ai answerlist the questions nobody answered
    aegis ai answer <uuid> --text "…"answer one; the worker picks it up
    aegis ai daemonrun the loop in the foreground

    A turn that asks through interact.* goes waiting and stays there until an answer or the timeout; the answer fills the row and the worker continues. A turn left running by a dead process is marked interrupted when the daemon starts — never resumed, because half its transcript already exists.

    Every event — deltas, tool calls, the final status — is published on the Bird topic ai, channel private, so a live view can follow a background turn without polling the database.

    #The two providers

    ProviderDriverEndpointDefault model
    DeepSeekdeepseekhttps://api.deepseek.com/v1deepseek-flash
    xAI (Grok)xaihttps://api.x.ai/v1grok-4.7

    Both speak the OpenAI-compatible /chat/completions shape, with SSE for streaming and reasoning_content for the reasoning stream. A third compatible endpoint is one module with a ProviderSpec and one entry in CATALOGUE.

    #The database

    TableWhat it holds
    ai_providersone row per endpoint: driver, URL, key, status, which is the default
    ai_modelsthe model catalogue: context window, output limit, feature flags, aliases
    ai_model_priceseffective-dated prices per model, kind and tier
    ai_agentsagent definitions: instructions, loop limits, model, parallel caps
    ai_agent_toolswhich tool an agent may call, with its permission
    ai_agent_skillswhich skills an agent carries, and in which order
    ai_agent_sub_agentswhich agents an agent may delegate to
    ai_toolsthe tool catalogue, grouped in packs
    ai_skillsprompt blocks, synced from skill.md or written by hand
    ai_chatsconversations, including the child chats of sub-agents
    ai_turnsone row per prompt: status, counters, cost, cancellation flag
    ai_messagesthe transcript; one assistant row per provider hop
    ai_tool_callsevery tool execution, including the ones that never produced a message
    ai_interactionsa question a turn is waiting on
    ai_memoriesfacts kept between conversations, scoped to an agent, a chat or the host
    ai_todosthe checklist of a conversation: what the agent planned and what is left

    Prices are effective-dated: the row with an empty effective_to is the current one. A sync that finds the same number leaves it alone, a different one closes the old row at that moment and opens a new one, so a past turn can always be repriced with the rate that was valid when it ran.

    The two invariants the schema enforces itself are one active default provider and one default model per provider; the store clears the previous row before it sets a new one.

    #Files

    text
    app/modules/ai/├── db.py              SQLite access and the migrations├── store.py           provider rows and the JSON helpers├── models.py          model and price rows├── sync.py            config + declarations -> the catalogue├── cli.py             `aegis ai providers`├── cli_models.py      `aegis ai models`└── providers/         one module per driver: base.py, deepseek.py, xai.py

    Default agents and skills are files, not code: storage/ai/agents/<slug>/ and storage/ai/skills/<category>/<name>/. They ship with the repository and are written into the database by aegis ai setup.