#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").
[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-…"| Key | Meaning |
|---|---|
default_agent | agent used when aegis ai prompt does not name one |
default_provider, default_model | what an agent without a model runs on |
max_turns | turns the background daemon runs at the same time |
max_steps | provider hops one turn may make |
parallel_agents, parallel_tools | concurrent sub-agents and tool calls |
toolbox | offer the loading gate instead of every tool schema on every hop |
shell_confirm | ask for a confirmation before a mutating tool runs |
interaction_timeout | seconds a turn waits for an answer |
request_timeout | seconds one provider request may take |
compact_auto | fold the oldest messages before a turn reaches the window |
compact_threshold | share of the window that triggers the fold (0.80) |
compact_keep_recent | messages always kept verbatim |
compact_keep_tokens | tokens of the tail the fold must not touch |
compact_buffer | room kept free below the window |
daemon | run 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
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 syncproviders 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:
⚠ sk-openai: no driver for that provider in this build--json prints the same listing as one object, for a script or the panel:
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.
| Pack | Tools | What it is for |
|---|---|---|
tools | explore, search | find and activate the other tools |
context | status, compact | how full the window is, and folding it |
aegis | info, docs_search, docs_read | the host and the manual |
aegis | command, services, tasks | the aegis command, the keeper, the tasker |
shell | run, ps | commands and processes on this host |
files | read, list, search, write, edit | the project tree |
chat | info, list, history, search | the transcripts in ai.db |
memory | remember, recall, list, get, update, forget | facts kept between conversations |
todo | add, list, update, remove, clear | the checklist of this conversation |
skills | list, read, search | the skill catalogue |
agents | list, call | who this agent may delegate to, and the call |
interact | ask, confirm, choose | questions the turn pauses on |
web | fetch | one 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.
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 synctools 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:
storage/ai/skills/<category>/<skill>/skill.mdskill.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.
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 syncThe 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.
| Rule | Why |
|---|---|
only agents in ai_agent_sub_agents | the operator decides who may be called |
| two levels deep | a delegate that delegates forever is a fork bomb |
parallel = true runs children beside each other | independent work should not queue |
max_parallel_agents caps it | the 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.
| Tool | What it does |
|---|---|
memory.remember | keep a fact, with its kind, tags and importance 0–5 |
memory.recall | search title, body and tags; a match records the use |
memory.list | the stored facts, best first |
memory.get | one memory in full |
memory.update | correct a fact instead of storing a contradictory copy |
memory.forget | archive 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.
| Tool | What it does |
|---|---|
todo.add | append a step |
todo.list | the plan as it stands |
todo.update | mark one active, done or cancelled |
todo.remove | drop one |
todo.clear | delete 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.
| Tool | What it does |
|---|---|
context.status | used tokens, window, percentage, whether a fold is due, how much a summary covers |
context.compact | folds 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:
storage/ai/agents/<slug>/agent.mdThe same +++ TOML block as a skill, with the agent fields; the body is the instructions that become the first block of the system prompt.
| Field | Meaning |
|---|---|
kind | master, sub-agent or utility |
model | model slug the agent runs on |
max_steps | provider hops one turn may make |
parallel | may it run sub-agents and tools concurrently |
max_parallel_agents, max_parallel_tools | the two caps |
tools | pack.* or one tool name |
skills | category/* or one slug |
sub_agents | the 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.
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 helperaegis 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
aegis ai setupaegis ai setup --checksetup 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
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
turn with a sentence that names it, before anything is spent.
summary of a folded window, and a runtime block (date, host, root, model).
tools.* and context.* always, plus whatever themodel activated earlier in this turn. That is why the model starts by exploring: a schema it never asked for is not in the request.
usage and the cost are stored before the tools run, so a reload sees the turn while it is still going.
ai_tool_calls and a toolmessage. A question (interact.*) is asked on the terminal and its answer becomes the tool result.
the chat goes back to idle.
#Failures and limits
A 400, 401 or 404 fails at once with the provider's message.
max_steps hops and says so (status: max_steps).Ctrl-C leaves the turn marked interrupted; the next run reads the sametranscript.
compact_threshold (80% of the window) the oldest messages are folded intoa summary before the hop, and the turn continues from it.
--json prints one object and nothing else:
{"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
aegis ai chataegis ai chat --chat <uuid>aegis ai chat --agent aegis --model deepseek-flash --no-streamA 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:
· Run aegis status 574ms · Explore tools 0ms ✖ Fetch https://example.invalid 12ms — cannot fetch the page| Command | What it does |
|---|---|
/help | the command list |
/new | start a new chat on the same agent |
/sessions | the last twenty chats, numbered |
/sessions <n> | switch to one (number or UUID prefix) |
/chat | the UUID of this chat, for --chat or the panel |
/model [slug] | show or change the model of this chat |
/context | used tokens, window, percentage |
/compact | fold the older messages now, with a written summary |
/tools | what this agent can call, grouped by pack |
/quit | leave (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.
| Command | What it does |
|---|---|
aegis ai jobs list | queued 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 answer | list the questions nobody answered |
aegis ai answer <uuid> --text "…" | answer one; the worker picks it up |
aegis ai daemon | run 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
| Provider | Driver | Endpoint | Default model |
|---|---|---|---|
| DeepSeek | deepseek | https://api.deepseek.com/v1 | deepseek-flash |
| xAI (Grok) | xai | https://api.x.ai/v1 | grok-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
| Table | What it holds |
|---|---|
ai_providers | one row per endpoint: driver, URL, key, status, which is the default |
ai_models | the model catalogue: context window, output limit, feature flags, aliases |
ai_model_prices | effective-dated prices per model, kind and tier |
ai_agents | agent definitions: instructions, loop limits, model, parallel caps |
ai_agent_tools | which tool an agent may call, with its permission |
ai_agent_skills | which skills an agent carries, and in which order |
ai_agent_sub_agents | which agents an agent may delegate to |
ai_tools | the tool catalogue, grouped in packs |
ai_skills | prompt blocks, synced from skill.md or written by hand |
ai_chats | conversations, including the child chats of sub-agents |
ai_turns | one row per prompt: status, counters, cost, cancellation flag |
ai_messages | the transcript; one assistant row per provider hop |
ai_tool_calls | every tool execution, including the ones that never produced a message |
ai_interactions | a question a turn is waiting on |
ai_memories | facts kept between conversations, scoped to an agent, a chat or the host |
ai_todos | the 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
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.pyDefault 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.