Aria

What This Is

Aria is a small program you run on your own computer or server. It lets you keep a team of AI helpers that all work together, like little co-workers.

Each helper is called an agent. Each agent has a name, a job, a personality, and a list of things it is allowed to do. You can talk to them from chat, the web app, or the terminal.

Three things make it different from a normal chatbot:

1. It remembers. Chats are saved, and important facts can be stored for later.
2. It learns. Agents can keep skills, rules, and taste notes instead of starting from zero every time.
3. It is a team. You are not stuck with one assistant. You can have an orchestrator, a builder, a writer, a designer, or whatever else you want.

Runtime Model

When Aria starts, it loads the database, memory, models, tools, agents, channels, automations, and the web/API server. The main boot file is src/index.ts.

Built-in agents vs your agents

The repo can ship with built-in agents like Aria and Bob, but those are just agent files. They are not special magic classes you can never change. You can add, remove, rename, or replace agents by editing the YAML files in agents/.

• Aria is the system helper. Setup, maintenance, channels, and system-level questions.
• Bob is the builder. He works on the product itself: code, Mission Control, tools, onboarding, and runtime features.
• Other agents can be orchestrators, workers, writers, researchers, designers, assistants, or anything else you want.

Hot reload

If you change an agent YAML file or a skill YAML file while Aria is running, the system notices and reloads it. You usually do not need to restart the whole app just to change an agent or a skill.

Message Flow

A message does not always reach agents in exactly the same way. It depends on where the message came from.

• Mission Control and the API can send directly to the agent you picked.
• A Telegram or Discord bot can be tied to one agent.
• The shared Aria bots can switch agents with /switch.
• If you mention one agent with @Name, the message can be routed to them.

But once the target agent is chosen, the path is simple:

System prompt contents

Agents do not use one frozen prompt forever. The prompt is rebuilt each turn from the agent config and the current state: personality, task mode, rules, core skill, recent context, tasks, tools, and user preferences.

Chat vs task replies

The same agent can reply in two different ways, depending on what you asked for.

• Chat mode is for normal conversation. The full personality shows up more.
• Task mode is for work. If you say things like “build”, “fix”, “write”, “install”, or “set up”, the agent can switch into a more focused working voice.

So if Sam is chatting with you casually, she may sound warm or witty. If you ask Sam to fix a bug, she should sound more direct and work-like. That behavior comes from persona and task_persona in the agent config.

Agents

An agent is a YAML file. That is the core idea. Put a file in agents/, and Aria can load it.

name: Samantha
role: orchestrator
persona: |
  You are direct, fast, and highly competent.
task_persona: |
  Break work into clear subtasks. Delegate when useful.
provider: zai-coding/glm-5v-turbo
tools: [shell, files, cron, contacts, apple, web]
permissions: auto
require_approval: [applescript_run, imessage_send, shell]
memory:
  private: true
  inherits: [user]
master_skill: personal-assistant-core
channels:
  telegram:
    bot_token: "..."
    allowed_users: ["123456"]
triggers:
  - on: cron
    schedule: "0 9 * * MON-FRI"
    do: "Review today's priorities and send me a concise briefing"
    deliver_to: [telegram]

Config fields that matter in practice

Orchestrators are a role, not a separate runtime type

There is no totally separate “orchestrator machine” hiding somewhere. An orchestrator is just an agent whose job is to plan, route, and delegate work. In some cases the runtime can stop an orchestrator from writing files or running shell commands directly so it delegates that work instead.

Tools

Tools are how agents do real work. Without tools, they can only talk. With tools, they can read files, run commands, search the web, save memory, schedule work, and more.

Two layers of availability

1. Runtime level: the tool has to exist in the running app first.
2. Agent level: the agent also has to be allowed to use it.

Current tool families

Permissions

Every tool call goes through a permission check. Safe read-only tools can pass easily. Dangerous shell commands are always blocked. Everything else goes through approval mode, auto mode, or bypass mode.

Memory, Skills, Feedback

Memory

Aria stores its state in SQLite at data/aria.db. That includes conversations, memories, tasks, logs, contacts, and more. Memory is split by agent, but agents can also inherit shared memory like the user namespace.

• conversations stores chat history by agent and channel.
• memories stores long-term facts, preferences, events, skills, and user facts.
• FTS5 is used for lexical search; embeddings are stored separately for semantic lookup.

Skills

Skills live on disk in data/skills/{agent}/ as YAML files. They can be improved over time, reloaded, and pinned as an agent's core skill.

Feedback and taste

Likes, dislikes, and style notes can also be saved. That way agents can slowly learn what kind of tone and output the user wants.

Tasks, Triggers, Dream

Task board

The task board is persistent and evented. Agents can create, assign, review, block, and complete tasks. Active tasks are injected into each agent's prompt, and review policies allow lightweight approve-or-revise loops.

Triggers and cron

The code now has a unified trigger engine in src/core/triggers.ts. The old crons field still works, but it is treated as backward-compatible input. Triggers can react to time, task events, tool completion events, and polling sources such as Gmail.

Dream runner

The current implementation is the dream runner in src/dream/: a nightly review flow where the built-in Aria agent uses supervisor tools to audit conversations, memories, rules, and follow-up opportunities across the team.

It is resumable, file-backed, and delivered through the same notification channels used by cron and trigger output.

Tunnel

The tunnel is what lets Aria live in one place and still reach another.

The most common setup is this:

• Aria runs on a VPS so it is always on.
• The tunnel client runs on your laptop or desktop.
• When the tunnel is connected, agents on the VPS can use tools on your own machine.

That means an agent can do things like:

• run a command on your machine with local_shell
• read or write local files
• use coding_task on a local repo
• make a web request through your home IP with local_proxy

Start the client with:

bun run tunnel --server ws://your-vps:3000/tunnel --secret your-secret

If the tunnel is not connected, those local tools do not work yet. The rest of Aria still works normally.

Channels

Channels are adapters. They receive messages, normalize them, apply commands and conversation-control behavior, target an agent, and persist the result.

Conversation control

A running session can queue a follow-up, steer the next pending message, or reject new work depending on the configured busy behavior. This exists across API, Telegram, Discord, and CLI paths.

Mission Control

Mission Control is the Next.js frontend in mission-control/. It talks to the Bun gateway on port 3000 by default and runs on port 4000 in local dev via bun run dev.

Current routes

• /chat for direct agent chat
• /agents for agent config, models, and channel settings
• /memory for memory inspection
• /tasks for the task board
• /cron for scheduled work
• /journal for daily logs
• /contacts for the personal CRM
• /rooms for shared multi-agent rooms
• /editor for the built-in markdown editor
• /activity for inter-agent activity
• /settings for keys, providers, and auth settings

Performance conventions

Route data lives in mission-control/src/lib/route-data/, sidebar navigation prewarms routes, and data requests go through the frontend API helpers and cache utilities rather than ad hoc fetches.

Extension Points

Add an agent

1. Create a YAML file in agents/.
2. Give it a persona, provider, tool access, and permissions.
3. Optionally add per-agent Telegram or Discord config under channels.
4. Save the file and let hot reload pick it up.

Add a tool

1. Create the tool file under src/core/tools/.
2. Export a ToolDefinition or factory returning tool definitions.
3. Register it in startup, typically from src/index.ts.
4. Expose it to the right agents via tool names or tags.

Add an API endpoint

Edit src/gateway/server.ts. The gateway already owns auth, chat, settings, agent management, and frontend serving, so new backend features usually land there.

Add a Mission Control page

1. Create mission-control/src/app/{name}/page.tsx.
2. Add a route-data file when the page needs data.
3. Wire the page into the sidebar.
4. Use the shared API client and caching utilities.

Repository Layout

agents/                    agent configs and templates
data/                      SQLite db, skills, files, audio, user context
docs/                      product and operator docs
mission-control/           Next.js frontend
src/
  core/                    agents, tools, providers, permissions, tasks
  cron/                    legacy cron parsing and scheduler
  dream/                   nightly review runner
  gateway/                 Hono API, auth, channel adapters, commands
  memory/                  database bootstrap and memory store
  setup/                   first-run setup wizard
  tunnel/                  VPS-to-local protocol and client/server
  index.ts                 runtime entrypoint