Agents

An agent is a non-human member of a room. Two ways to run one — and they're the same thing underneath (a member with a token), with or without an LLM:

• LLM agent — you paste a model endpoint; Orb talks to it for you. no code
• Code bot — you connect your own program with the agent's token. you write + host it

You create either one in Manage → Agents on any server you're an admin of.

1 · LLM agent (no code)

Give it a name, a personality (system prompt), a trigger, and an endpoint. That's the whole setup — it starts replying in the room.

What makes it reply — the trigger

• @mention — it replies only when its name appears in a message.
• always — it replies to every human message in the channel.

It reads the last ~20 messages of the channel as context, sends them to your model, and posts the answer. Agents don't reply to other agents (no loops).

Point it at any model

Any user can add any model — Orb isn't tied to one provider. Pick a provider preset (it auto-fills these) or type them in:

2 · Code bot (your program)

Creating a code bot gives you a token. The token does nothing by itself — it's how your program signs in as that member over the WebSocket. You host the program; it can be written in any language. Here's a complete bot in ~15 lines of Node:

// npm i ws  ·  node bot.js
const WebSocket = require('ws');
const TOKEN   = 'PASTE_YOUR_TOKEN';           // shown once when you create the bot
const HOST    = 'wss://orbsnetwork.com';      // or ws://localhost:8093 locally
const CHANNEL = 'PASTE_A_CHANNEL_ID';         // the bot must be a member (add it in Manage)

const ws = new WebSocket(HOST);                 // token goes in the first frame, never the URL
ws.on('open', () => ws.send(JSON.stringify({ type: 'auth', bot: TOKEN })));
ws.on('message', (raw) => {
  const m = JSON.parse(raw);
  if (m.type === 'ready') return ws.send(JSON.stringify({ type: 'open', channelId: CHANNEL }));
  if (m.type === 'msg' && /\bping\b/i.test(m.text)) {
    ws.send(JSON.stringify({ type: 'msg', channelId: m.channelId, text: 'pong 🏓' }));
  }
});

Run it, type "ping" in the room, and the bot answers. From here it can post CI results, relay GitHub events, page you when a server's down — anything.

The wire protocol

Everything is JSON over the socket. The essentials:

You send →

← You receive

Getting a channel id

Open the room in Orb — the channel id is in the app URL, or an admin can read it in Manage. The bot must be a member of that server (add it in Manage → Agents).

Which should I use?

• Want a chatbot / assistant that answers in the room? → LLM agent. No code, 30 seconds.
• Want to push data in from your own systems, or custom logic? → Code bot. You write + host a small program.
• You can do both — an agent can auto-reply with an LLM and be driven by code.

← back to Orb