Concepts

Agent OS

• Agent OS — Lightweight Bun-based Agent Operating System. Runs locally (default 127.0.0.1:3010). Manages micro-agents, skills, task queue, scheduler, graphs, memory, and messaging channels.
• Home directory — ~/.agent-os/ (or AGENT_OS_HOME). Contains config.json, agents/, skills/, configs/, graphs/, workspaces/, and the SQLite database.

Agents

• Agent — A configured AI assistant: id, name, model, personality, list of skills and tools, optional schedule. Stored in the database (default) or as JSON in ~/.agent-os/agents/.
• Agent runtime — Executes one task per run: build prompt, call LLM, parse tool calls, execute tools, repeat until done or limits. Uses workspace ~/.agent-os/workspaces/{agent_id}/ for file tools.
• Workspace — Per-agent sandbox directory. File-access tools are restricted to this path. Templates (e.g. IDENTITY.md, USER.md) can be copied here when an agent is created.

Skills & tools

• Skill — An installable module under ~/.agent-os/skills/<name>/. Contains skill.yaml (or SKILL.md) and optional tools.yaml. Defines when and how to use tools; tools are registered in the central tool registry.
• Tool — A callable capability the model can use (e.g. echo, time, or tools from skills). Each tool has id, name, description, and input schema. Execution is handled by the runtime.
• Tool registry — Central registry of all tools (built-in + from skills). Agents declare which tools they use; runtime only exposes those to the LLM.

Tasks & scheduler

• Task — A single run request for an agent (task text, agent id, status). Stored in the database; lifecycle: queued → running → completed/failed.
• Task queue — Queue of pending tasks. Workers pull and run them (max workers configurable).
• Scheduler — Cron-based: enqueues tasks for agents that have a schedule (cron expression) and optional schedule_input (prompt per tick).

Graphs

• Graph — A workflow of agents: nodes (each tied to an agent) and edges (from → to). Stored under ~/.agent-os/graphs/. Execution runs nodes in dependency order; output of one agent can be passed to the next.

Memory & conversations

• Memory — Long-term storage (SQLite, optional vector search). Skills like memory expose tools to write and search memories. API: POST /api/memory/write, GET /api/memory/search, DELETE /api/memory/:id.
• Conversation — A chat thread (conversation_id, messages). Used by the dashboard and channels to keep context. Can be summarized for long threads.

Channels

• Channel — A messaging platform (Telegram, Slack, Discord, Signal, Viber). The server receives incoming messages via webhook (or polling for Telegram), resolves the default agent for that channel, runs the agent with the message, and sends the reply back.
• Webhook — Channel-specific endpoint (e.g. POST /api/channels/telegram/webhook). Config (bot token, signing secret, default agent) is stored in ~/.agent-os/config.json and editable in Settings.

Config & storage

• Config — ~/.agent-os/config.json. Holds API keys (OpenAI, OpenRouter, etc.), channel tokens and default agents, and other runtime settings. Env vars can override.
• Skill config — Per-skill key/value storage in ~/.agent-os/configs/<skill_id>.json. Used for API keys and options required by skills.
• Registry / store — Optional. A remote registry URL returns a list of skills (slug, name, description, url). The dashboard and POST /api/skills/install use it to install skills by slug.