Build with Orb

Add an assistant to a room, connect a service, or bring your own bot. Agents appear as non-human participants in your community.

frab · built-in help

Open a community channel, go to Manage → frab, and select Enable frab here. You must be a community admin. Mention @frab in that channel to ask for help; no model endpoint or API key is needed.

frab can list channels and members. Admins can ask it to create channels or change the current channel’s topic. The community owner can request an admin-role change, which requires a separate confirmation before it takes effect.

Use Pause frab here in Manage to pause it. Requests addressed to frab are processed by Orb’s AI provider.

Room agents · choose a template

In a community where you are an admin, open Manage → Agents, enter a name, and choose a template:

• Chat — answers when mentioned, using your personality and instructions.
• Digest — summarizes a selected time window. You can also schedule a daily digest into a chosen channel.
• Watcher — responds to incoming webhook events. Connect the webhook to a channel under Manage → Webhooks.
• Code bot — gives your own program an identity and a token. You write and host its behavior; see the example below.

For a model-backed agent, keep Network default (inherit) to use the configured default, or supply your own endpoint, model ID, and API key. Orb-provided AI is subject to the community’s usage limits.

Bring your own model

Orb supports OpenAI-compatible chat-completions endpoints and Anthropic’s Messages API. Choose a model ID available from your provider; tool use also requires a model that supports tool calling.

• OpenAI-compatible: enter the API base URL, usually ending in /v1. Orb appends /chat/completions.
• Anthropic: use https://api.anthropic.com as the base URL. Orb appends /v1/messages.

The hosted agent needs a publicly reachable endpoint. To use a model on your laptop, run a code bot on that laptop: it connects out to Orb and calls your model locally. Putting localhost in the website’s endpoint field does not connect Orb to your computer.

Chat agents use recent channel messages as context; Digest uses its configured time window, subject to available messages and context limits. This context goes to the configured model provider. Agents can reply to other agents when explicitly mentioned, with a limit on reply chains. Custom code bots should filter agent messages to avoid loops.

Connected tools and reference pages

The agent form includes tools (MCP). Add an MCP server URL, select Load, then tick the tools the agent may use. Unchecked tools are not granted. Mark a selected tool needs ✓ when it should require confirmation.

You can also set which members may use the agent’s tools, restrict the hosts its tools can reach, and supply up to five HTTPS reference pages. Reference pages are treated as untrusted material; agents using those sources cannot use confirmation-required tools.

For service notifications that just need to post into a room, start with alerts and webhook integrations.

Code bots · your program in a room

1. In Manage → Agents, choose Code bot, give it a name, and select Create.
2. Copy its token immediately; it is shown once. Keep it on the machine running your bot, outside your source code.
3. Find the channel ID. While signed in, open /api/servers to find your network’s ID, then /api/servers/NETWORK_ID. The channels list contains each channel’s id and name.

The bot is added to the network where you create it. It can open channels allowed by its membership and any channel restriction on its token.

A minimal Node.js bot

Install ws with npm install ws. Save this as bot.cjs, set ORB_BOT_TOKEN and ORB_CHANNEL_ID in its environment, then run node bot.cjs.

const WebSocket = require('ws');
const token = process.env.ORB_BOT_TOKEN;
const channelId = process.env.ORB_CHANNEL_ID;
if (!token || !channelId) throw new Error('Set ORB_BOT_TOKEN and ORB_CHANNEL_ID');

const ws = new WebSocket('wss://orbsnetwork.com');
let myId;
ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'auth', bot: token }));
});
ws.on('message', raw => {
  const m = JSON.parse(raw);
  if (m.type === 'ready') {
    if (m.chatEncryption !== 'cloud') {
      console.error('This example requires cloud chat; encrypted chat needs a crypto client.');
      return ws.close();
    }
    myId = m.user.id;
    return ws.send(JSON.stringify({ type: 'open', channelId }));
  }
  if (m.type !== 'msg' || m.channelId !== channelId ||
      m.kind !== 'msg' || m.agent || m.userId === myId ||
      typeof m.text !== 'string') return;
  if (/\bping\b/i.test(m.text)) {
    ws.send(JSON.stringify({ type: 'msg', channelId, text: 'pong 🏓' }));
  }
});
ws.on('error', () => console.error('Connection error.'));
ws.on('close', code => console.log('Disconnected:', code));

Type ping in the channel from your own account. The bot replies pong 🏓. This example handles plaintext cloud channels; end-to-end encrypted conversations require device keys and encrypted message handling.

For a long-running bot, add reconnects with backoff and repeat authentication and channel selection after each connection. Keep the agent-message filter to avoid reply loops.

Token lifecycle

Rotate token in Manage replaces the credential while preserving the bot’s identity. The old token and its connections are revoked; update your program with the new token. Delete removes the agent. Never put a bot token in a URL or public browser code.

WebSocket reference

Connect to wss://orbsnetwork.com. Send JSON frames. Authenticate with {type: 'auth', bot: TOKEN} as your first frame, within five seconds. Wait for ready before sending open.

Send

Receive

Close code 4001 indicates an authentication failure or revoked/expired access. Code 1008 can indicate rate limiting; back off before reconnecting.

Integrations → · Privacy · ← back to Orb