Common Issues

Common Issues

Server not starting

Problem: The Agent OS server doesn’t start or you can’t reach http://127.0.0.1:3010.

Solutions:

1. Bun required — This app runs on Bun. Use bun run dev or bun run src/index.ts (not Node).
2. Port in use — Another process may be using port 3010. Change PORT in env or stop the other process.
3. Dependencies — From the sulala directory run bun install and try again.
4. Build — If using the built CLI, run bun run build first so dist/index.js exists.

No agents showing

Problem: Dashboard or API returns an empty agent list.

Solutions:

1. Onboard first — Run sulala onboard to create ~/.agent-os/, the database, and seed agents from the seed dir (e.g. data/agents).
2. Database path — Default is ~/.agent-os/database.db (or AGENT_MEMORY_DB_PATH). Ensure the file exists and is writable.
3. Seed dir — If using SQLite, agents are seeded from AGENT_OS_SEED_AGENTS_DIR (e.g. data/agents) when the DB is empty. Add JSON agent files there and run onboard again (or create agents via API/dashboard).

Skills not loading

Problem: Installed skills don’t appear or tools are missing.

Solutions:

1. Path — Skills live in ~/.agent-os/skills/ (or AGENT_OS_SKILLS_DIR). Each subfolder must have skill.yaml or SKILL.md.
2. Install system skills — Use the dashboard “Install system skills” or POST /api/skills/install-system to copy from the seed dir (data/skills).
3. Restart — After adding or changing skill files, restart the server so the loader picks them up.
4. Assign to agent — Edit the agent and add the skill id to its skills array.

Channel webhook not receiving messages

Problem: Telegram/Slack/Discord/Signal/Viber doesn’t trigger the agent.

Solutions:

1. Config — In Settings → Channels, set the token and default agent id for that channel.
2. Webhook URL — Must be HTTPS for production (Telegram, Viber, etc.). Use ngrok or a reverse proxy and set the webhook URL on the platform to your public URL (e.g. https://your-domain.com/api/channels/telegram/webhook).
3. Set webhook — For Telegram and Viber, call the set-webhook endpoint (or use the dashboard) to register the URL with the platform.
4. Slack/Discord — Ensure the app is configured to send events or interactions to your webhook URL and that the signing secret (Slack) or public key (Discord) is set in config for verification.

“Agent not found” when running

Problem: sulala run <agent_id> ... or API returns “Agent not found”.

Solutions:

1. Correct id — Use the exact agent id (e.g. personal_agent). Check GET /api/agents for the list.
2. Database — When using the CLI, the same DB as the server is used when AGENT_MEMORY_DB_PATH (or ~/.agent-os/database.db) exists. If you only added agents via the dashboard, they’re in the DB; ensure the CLI isn’t using a different DB path.
3. Onboard/update — Run sulala onboard (first time) or sulala update to ensure seed agents are installed.

API keys / LLM errors

Problem: Agent run fails with auth or model errors.

Solutions:

1. Set keys — In Settings (or ~/.agent-os/config.json), set the API key for the provider the agent uses (e.g. openai_api_key, openrouter_api_key).
2. Env override — You can set OPENAI_API_KEY, OPENROUTER_API_KEY, etc. in the environment; they override config.
3. Model name — Ensure the agent’s model field matches a valid model id for that provider (e.g. OpenRouter model id, or gpt-4o for OpenAI).