Platform

Agent OS

Lightweight Bun-based Agent Operating System — agents, skills, task queue, scheduler, graphs, memory, and channels.

Overview

Sulala Agent OS is a local-first AI agent platform built on Bun. It runs on 127.0.0.1:3010 by default and provides:

Micro-agents — Create and run multiple agents; each has a model, personality, skills, and tools
Skills — Installable modules (~/.agent-os/skills/<name>/) with skill.yaml (or SKILL.md) and optional tools.yaml
Task queue & scheduler — Background workers and cron-based scheduled runs per agent
Agent graphs — Multi-agent workflows (nodes and edges) run in dependency order
Memory & conversations — Persistent conversations and long-term memory (write/search API + memory skill)
Channels — Talk to agents via Telegram, Slack, Discord, Signal, or Viber (webhooks)
Dashboard & API — Web UI and REST API for agents, tasks, skills, graphs, settings, and chat

All data and config live under ~/.agent-os/ (or AGENT_OS_HOME). Credentials are stored in config.json or env; never in the repo.

Architecture

Layer	Role
HTTP server	Bun.serve on port 3010; REST routes + WebSocket `/api/events`
Agent registry	Load/save agents from SQLite (default) or `~/.agent-os/agents/` JSON files
Agent runtime	LLM loop: prompt → model → tool calls → execute → repeat; workspace per agent
Tool registry	Central registry of built-in and skill tools; agents declare which tools they use
Skill loader	Load skills from `~/.agent-os/skills/`; register tools from `tools.yaml`
Task queue	Queued tasks; worker pool runs agents; lifecycle: queued → running → completed/failed
Scheduler	Cron: enqueue tasks for agents with `schedule` and optional `schedule_input`
Graph runner	Execute graph nodes in order; pass output between agents
Memory	SQLite (+ optional vector search); API and memory skill for write/search
Channels	Webhook handlers per channel; resolve default agent, run agent, send reply

Quick start

From repo:

cd sulala
bun install
bun run cli onboard    # first time: create ~/.agent-os, config, seed agents/skills
bun run dev           # start server

Run an agent:

bun run cli run echo_agent "What is 2+2?"

HTTP:

curl http://127.0.0.1:3010/api/agents
curl -X POST http://127.0.0.1:3010/api/agents/run \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"echo_agent","task":"Hello!"}'

CLI

sulala version          # Show version
sulala start            # Start server (foreground)
sulala start --daemon   # Start in background (writes PID to ~/.agent-os/sulala.pid)
sulala stop             # Stop daemon
sulala onboard          # First-time setup: config, DB, seed agents & skills
sulala update           # Update system agents and skills (from seed dirs)
sulala run <agent_id> <task>   # Run agent with one-off task

Config and data: ~/.agent-os/. For full options see CLI reference.

Skills

Skills are YAML + optional tools: each skill is a folder under ~/.agent-os/skills/<name>/ with:

skill.yaml or SKILL.md — Name, description, optional metadata and embedded YAML
tools.yaml — Optional; defines HTTP or exec-based tools for the skill
config.schema.json — Optional; schema for skill config (dashboard shows form)
SETUP.md — Optional; setup instructions

Agents declare skills: ["weather", "memory"] in their config. The loader registers each skill’s tools into the tool registry; the runtime only exposes tools that belong to the agent’s skills (and built-in allowlist). Skill-specific config is stored in ~/.agent-os/configs/<skill_id>.json.

Install: copy folder to ~/.agent-os/skills/, or use Install system skills (dashboard / POST /api/skills/install-system), or install from a store registry via dashboard or POST /api/skills/install.

Agent API (run & stream)

Method	Path	Description
GET	`/api/agents`	List agents
POST	`/api/agents`	Create agent
PUT	`/api/agents/:id`	Update agent
DELETE	`/api/agents/:id`	Delete agent
POST	`/api/agents/run`	Run agent (JSON body: agent_id, task, conversation_id?, etc.)
POST	`/api/agents/run/stream`	Run agent with streaming response

Other: /api/tasks, /api/logs, /api/graphs, /api/graphs/run, /api/memory/write, /api/memory/search, /api/conversations, /api/settings, /api/skills, /api/channels/telegram/webhook, etc. See Agent API and server routes in the repo.

AI models

Supported via config/dashboard: OpenRouter, OpenAI, Anthropic, Google (Gemini), and Custom (model id). Set API keys in ~/.agent-os/config.json or env: OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc. Agent config stores model (and optional provider); the runtime uses the corresponding key.

Config

Server: PORT (default 3010), HOST (default 127.0.0.1)
Paths: AGENT_OS_HOME (default ~/.agent-os), AGENT_OS_AGENTS_DIR, AGENT_OS_SKILLS_DIR, AGENT_MEMORY_DB_PATH
LLM: API keys in config or env (see above)
Channels: Telegram, Slack, Discord, Signal, Viber tokens and default agent ids in config; editable in Settings

See Agent configuration for full env and config file reference.

Requirements

Bun 1.0+
TypeScript (source); build output runs on Bun

Project layout (sulala)

sulala/
├── src/
│   ├── core/       # config, agent-registry, runtime, llm, tool-registry, tasks, events, graphs, plugins
│   ├── http/       # handlers, telegram, slack, discord, signal, viber, memory, conversations
│   ├── skills/     # loader (skill.yaml, tools.yaml)
│   ├── tools/      # echo, time, exec, run-agent
│   ├── db/         # memory-store (SQLite)
│   ├── types/      # agent config schema
│   ├── server.ts   # Bun HTTP server + routes
│   ├── index.ts    # entry
│   └── cli.ts      # sulala CLI
├── data/           # seed agents, skills, templates
└── roadmap.md      # Full roadmap and phases

For phases and future work, see Roadmap and sulala/roadmap.md in the repo.

Edit this pageorReport an issue

Self-Hosting

Run Sulala Agent OS on your own infrastructure — server, channels, and optional store.

Store API Contract (for Agent OS)

Contract that an optional skill store should follow so Agent OS can list and install skills.