Quick Start

Goal

Run Sulala Agent OS on your machine: create the config directory, seed agents and skills, start the server, and run an agent from the CLI or dashboard.

Prerequisites

• Bun 1.0 or later. Install from bun.sh.
• An LLM API key (OpenAI or OpenRouter). Set OPENAI_API_KEY or OPENROUTER_API_KEY in the environment or via Settings after onboarding.

Step 1: Install and run

From the repo (sulala package):

cd sulala
bun install

First-time setup (onboard):

bun run cli onboard

This creates ~/.agent-os/, writes config.json, creates the database, and seeds default agents and skills.

Start the server:

bun run dev

Or from the built CLI:

bun run build
./dist/cli.js start

When the server is running, you’ll see: Agent OS server running at http://127.0.0.1:3010. Open the dashboard at http://127.0.0.1:3010 (if the dashboard is served from the same origin or configured separately).

Step 2: Run an agent

From the CLI:

AGENT_OS_AGENTS_DIR=./data/agents bun run cli run echo_agent "What is 2+2?"

Or, after onboarding (agents are in the DB):

bun run cli run personal_agent "Hello, what can you do?"

Via HTTP:

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

From the dashboard: Open the Agents page, pick an agent, and use the chat or run form.

Step 3: (Optional) Install more skills

Skills live under ~/.agent-os/skills/. You can:

• Install system skills — From the dashboard: Settings or Skills → Install system skills. Or call POST /api/skills/install-system.
• Install from a store — If you use a skills store (registry URL in Settings), use the dashboard to browse and install by slug, or POST /api/skills/install with { "slug": "weather" }.
• Upload a skill — POST /api/skills/upload with a zip, or add a folder manually under ~/.agent-os/skills/<name>/ with skill.yaml (or SKILL.md) and optional tools.yaml.

After adding skills, assign them to agents in the Agents page (edit agent → skills).

Step 4: (Optional) Configure channels

To talk to agents from Telegram, Slack, Discord, Signal, or Viber:

1. Create a bot or app on the platform and get the token/credentials.
2. In the dashboard go to Settings → Channels and configure the channel (token, signing secret if needed, default agent).
3. Expose your server over HTTPS (e.g. ngrok) and set the webhook URL for that channel. Use the set-webhook endpoint for Telegram/Viber if available.

See Agent OS and channel-specific docs (e.g. TELEGRAM_SETUP.md in the repo) for details.

Summary

Next: read Agent OS, CLI reference, and Skills authoring for details.