Quick start
Before you start
Section titled “Before you start”- Bun 1.4.4 or newer.
- PostgreSQL.
The project
initcreates has adocker-compose.ymlthat runs one. - A Discord bot: an application with a bot user, the Message Content intent turned on, and an invitation to your server.
- A model login: the API key of the provider of the model you choose (
ANTHROPIC_API_KEYforanthropic/...), or a login made with Pi. - An address that reaches the process from the internet, such as a tunnel, because Discord fetches the agents’ avatars from it.
This page sets up a Discord project.
For a project without Discord, where people your OpenID Connect provider signs in chat on the web, run npx pi-roundtable init my-desk --adapter web and follow the web chat package instead.
Upgrading from 0.7? See Migrating to 0.8.
Create and start a project
Section titled “Create and start a project”-
Create the project.
initwrites a working project without asking for secrets. It refuses to write anything when Bun is missing or too old, or when a file it would create already exists.Terminal window npx pi-roundtable init my-bot # or: bunx pi-roundtable init my-botcd my-bot -
Install dependencies and start PostgreSQL.
Terminal window bun installdocker compose up -d -
Copy
.env.exampleto.envand fill it in. Bun loads.envby itself, and.gitignorekeeps it out of Git.Terminal window cp .env.example .env -
Run
doctor. In a fresh project, only credentials you have not entered yet fail the checks, anddoctornames them.Terminal window bunx roundtable doctor -
Start the bot.
Terminal window bunx roundtable start
The .env file
Section titled “The .env file”.env.example says where each value comes from.
| Variable | What it is |
|---|---|
DISCORD_TOKEN |
The bot’s token, from the application’s Bot page |
DISCORD_GUILD_ID, DISCORD_ENTRY_CHANNEL_ID |
The server and the channel where the coordinating agent lives (turn on Developer Mode, then right-click to copy ids) |
OWNER_ID, OWNER_NAME |
You: the one person who can change everything |
DATABASE_URL |
PostgreSQL; the default matches docker-compose.yml |
MODEL |
The agents’ model, <provider>/<id> |
PUBLIC_URL |
The address that reaches this process from the internet |
What doctor checks
Section titled “What doctor checks”bunx roundtable doctor checks in this order, and prints each check as passed or failed with how to fix it:
- Bun’s version.
.envhas a value for every variable.env.examplelists.roundtable.config.tsagainst its schema, naming the failing key.- Every plugin loads, no two share a name, and the registration is valid.
- Whom
accessserves: the owners, and a warning wheneveryone: trueadmits everyone on every surface of a host with more than one. - Whether a plugin fills the
imagesslot. The check passes with or without one; agents’ avatars are composed characters and do not use an image provider. - PostgreSQL is reachable and migratable.
- The principals: a dry run of what the next start makes from the people the database already knows, a configured owner’s identity linked to someone else (which stops the start), and a disabled owner.
- The Discord token is valid, the bot is in your server, the Message Content intent is on, and the bot has the permissions it needs in the entry channel (including Pin Messages). When the bot is not in the server, the fix is an invitation link that asks for exactly those permissions.
- The model login exists.
PUBLIC_URLis a well-formed address; with--reachableit also has to answer, which is only true while the bot runs.
It exits non-zero on any failure and changes nothing it checked.
What start does
Section titled “What start does”bunx roundtable start runs the checks that need no network, stops with the same message doctor prints when one fails, and otherwise starts the bot.
The running bot gives the agents in agents.ts their channels, and /roundtable schedule list shows the schedules of every channel.
See Your first conversation for where to write first.
On SIGTERM or SIGINT it finishes running work before it stops.
To give your agents tools from Notion, a calendar, or any other MCP server, see MCP connectors and remote MCP.