Settings overview
roundtable.config.ts holds the settings and the list of plugins.
It exports one object with export default { ... } satisfies RoundtableConfig.
A key that is not on this page is an error that names the closest known key:
config <key>: unknown key. Did you mean "<closest>"? The keys here are ...A required key that is missing, or a value of the wrong kind, stops roundtable doctor and roundtable start and names the key.
Required keys are marked below; each one is a non-empty string.
The file init writes
Section titled “The file init writes”The project that roundtable init creates reads its credentials and ids from .env through a small env helper, so nothing secret sits in this file.
See Environment variables for where each value comes from.
import type { RoundtableConfig } from "pi-roundtable";import { agents } from "./agents.ts";import { hello } from "./plugins/hello.ts";import { selfCompact } from "./plugins/self-compact.ts";
// Credentials and ids come from .env, which Bun loads on its own; nothing secret belongs in this file.const env = (name: string): string => process.env[name] ?? "";
export default { name: "Roundtable", access: { owners: [ { name: env("OWNER_NAME"), principal: env("OWNER_ID"), identities: [`discord:${env("OWNER_ID")}`], }, ], }, discord: { token: env("DISCORD_TOKEN"), guild: env("DISCORD_GUILD_ID"), entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"), }, database: { url: env("DATABASE_URL") }, // Paths are relative to the project directory, where the roundtable command runs. dataDir: "./data", model: env("MODEL"), http: { publicUrl: env("PUBLIC_URL") }, prompts: { shared: "./persona/shared.md" }, agents, plugins: [selfCompact, hello],} satisfies RoundtableConfig;Identity
Section titled “Identity”| Key | Type | Default | Meaning |
|---|---|---|---|
name |
string | "Roundtable" |
The assistant’s display name in the text the bot shows. |
Discord
Section titled “Discord”Leave discord out for a host without Discord: no Discord plugin, and with no agents, no agent server and no skills, while every conversation a plugin runs through context.turns still works.
With agents, the team runs without Discord in the rooms of a surface that hosts them, such as the web console, and the host refuses to start when none does; see Agents and avatars.
roundtable init --adapter web creates such a project around the web chat.
The same settings may also come as an adapter, adapters: [discord({ ... })] with discord from pi-roundtable/discord; configure Discord in one place, not both.
| Key | Type | Default | Meaning |
|---|---|---|---|
discord.token |
string, required with Discord | none | The bot token. Keep it in .env. |
discord.guild |
string | none | The id of the agent server’s guild, where the agents’ channels, categories and #dashboard live. Left out, Discord keeps serving the plugins’ claims, the slash commands and the owner’s direct messages in every guild the bot is in, and the team lives in the app’s rooms as without Discord: agents is required (unless agentServer is false), coordinator names the coordinator, and http.publicUrl is optional. |
discord.entryChannel |
string, required with discord.guild unless agentServer is false |
none | The id of the channel the coordinator lives in. Without discord.guild it is a ConfigError. |
discord.rootCommand |
string | the lowercase name, with each run of characters other than a-z, 0-9, and - replaced by - |
The root slash command, without the slash. See Slash commands. |
discord.admin |
boolean | true |
Whether the owner’s conversations get the discord_* administration tools. false leaves the discord-admin addon out. |
discord.refusalHint |
string | none | Text added as it is to the refusal a non-owner gets from the root command. Include the space or punctuation your language needs before it. |
discord.agentMemory |
"everyone" or "owners" |
"everyone" |
"owners" gives the memory block and the memory tools only to owner-tier turns in the agents’ channels. |
discord.agentSpeakers |
"everyone" or "owners" |
"everyone" |
"owners" lets only an owner-tier speaker start a turn in the agents’ and groups’ channels; doctor warns when admins or members are admitted on Discord with this unset. |
discord.channelContext |
object, or false |
{} |
What a turn reads of the channel around the message addressed to the assistant: fetch (default 50, at most 100), keep (15), similarity (0.8), messageChars (500), botMessageChars (80), peerMessageChars (4000, for a bot discord.peerBots lists), starter (false; true always adds a thread’s opening message), conversation (code only; names the conversation a turn runs in, so a second person who asks in a thread gets what an earlier one’s turn already read), foreignWebhook (code only), authors (code only) and attachments ({ images: 0, maxBytes: 10 MiB }). false turns it off. |
discord.peerBots |
{ allow, maxRounds? } |
none | The other bots the host answers, so separate bots can talk: allow lists their user ids, each a string or { id, guilds?, channels?, yields? }. With yields: true the host leaves to that bot a person’s message that mentions or replies to both of them (where the entry lists it): only the bot answers, and it can hand over by mentioning the host; set it on one side only. Explicit ids only, with no wildcard and no “all bots”; a bad id stops the start. A listed bot’s mention or reply is answered like a guest’s, as far as access serves its identity (discord:<id>); the Discord roles the bot holds are not read. maxRounds (default 3) is how many of their messages in a row a channel answers; a person’s message starts the count over. Left out, every bot is ignored. |
discord.freshMarker |
string, or false |
─── new conversation ─── |
The divider the assistant posts in a server channel or thread when its conversation starts over. false posts none. |
discord.memberEvents |
boolean | false |
Asks Discord for the privileged Server Members intent, so plugins hear each member that joins the server (the memberJoined event). Switch on Server Members Intent under Bot in the Developer Portal first, or the connection is refused; roundtable doctor checks it. |
discord.voice |
boolean | false |
Lets plugins join the server’s voice channels through DISCORD.voice and hear each speaker, such as a plugin that records a meeting. The bot asks Discord for the Guild Voice States intent, which is not privileged and needs no change in the Developer Portal, and loads its voice packages as it starts. It needs View Channel and Connect in a channel it joins. |
discord.formatting |
string, or false |
Markdown renders except tables | What the model is told, in English, about how a reply renders in Discord. false tells it nothing. |
discord.cardGraceSeconds |
integer from 1 to 86400 | 120 |
How long a turn waits for an approval card or an ask_user card before it ends and leaves the card open. |
discord.cardCopies |
{ keepDays?, keep? }, or false |
30 days, newest 100 | How long the text behind an approval card’s copy button is kept in card-copies.json under the data directory. The whole texts behind the agents’ message cards follow it, the newest 300, in intercom-texts.json. false keeps them in memory only. |
discord.attachmentDownload |
{ deadlineMs?, idleMs? } |
60000 and 10000 |
The time the files of one message (and the one it replies to) have to download, and how long a file may send no byte before it is given up. Each is from 1000 to 600000. |
agentServer |
false |
the agent server runs | false leaves the agent server out of a host that has discord: no agent team, no #dashboard channel or pinned message, no agent channels or routes, no coordinator, and no skills addon. Discord, access, memory, commands and the plugins’ claims work as before. discord.entryChannel and http.publicUrl become optional, and so is discord.guild. Setting it together with agents, skills, ops.agent, discord.agentMemory, discord.agentSpeakers or discord.attachmentDownload is a ConfigError naming both keys, and a plugin that needs the agent server (the web console’s agents and rooms panes, remote-mcp’s default conversation) stops the start. doctor reports the agent server as off and skips the entry-channel check. There is no true; leave the key out to keep the agent server. |
adapters |
list of adapters | none | The chat networks the host talks through, each made by its factory. A Discord adapter takes the discord settings above. A chat network that comes as a plugin, such as the web chat, stays in plugins. |
Storage and files
Section titled “Storage and files”| Key | Type | Default | Meaning |
|---|---|---|---|
database.url |
string, required | none | The PostgreSQL connection URL. |
dataDir |
string, required | none | Where the process keeps its files, such as pictures, attachments, and skills. |
workDir |
string | <dataDir>/work |
The agents’ shared working directory. |
agentDir |
string | <dataDir>/pi |
Pi’s agent directory, which holds the model logins. See Models. |
scratchDir |
string | <os temp dir>/<slug>-scratch, the slug being discord.rootCommand, or the lowercase name without Discord |
The agents’ scratch directory: their shell runs with TMPDIR pointing to it, and writes and removals inside it run without a hold. |
shellEnv |
{ pass?: string[], set?: Record<string, string> } |
none | What the agents’ shell gets of the host’s environment besides PATH, HOME, USER, LOGNAME, SHELL, the locale (LANG, LANGUAGE, LC_*), TZ, TERM, TMPDIR, the proxy and certificate variables: pass names more host variables, such as GH_TOKEN for gh and git push in the shell (none when not given); set gives fixed values. No other host variable, secret or not, reaches the shell. |
attachments.retention |
{ maxAgeMs, sweepEveryMs? } |
none | Removes the files turns used once they are maxAgeMs old, and sweeps at start and every sweepEveryMs (default one hour). Left out, used files live as long as their conversation. |
conversations.keepDays |
object of whole days by conversation kind | none | A daily sweep deletes a recorded conversation of a listed kind that was last active longer ago. A kind not listed is kept. |
conversations.keep |
function from a conversation record to true or false |
none | Asked for each conversation the sweep would delete; true keeps it for now (a support conversation whose ticket is still open), and it is asked again at the next sweep. A function that throws keeps the conversation and is logged. |
Models
Section titled “Models”| Key | Type | Default | Meaning |
|---|---|---|---|
model |
string, required | none | The agents’ model, written <provider>/<id>. |
thinking |
"off", "minimal", "low", "medium", "high", or "xhigh" |
"medium" |
The level a turn thinks at when its judge cannot pick one. |
judge.model |
string | the value of model |
The model that judges small questions. |
judge.threshold |
number from 0 to 1 | 0.6 |
How sure a judge must be before its answer is used. |
delegation.model |
string | the value of model |
The model that runs delegated tasks. |
delegation.thinking |
same levels as thinking |
"medium" |
The thinking level of delegated tasks. |
effortPolicy |
function from a turn to its effort rule | none | Decides how each turn that thinks at the judge’s choice is decided, instead of the default. Code only. |
The Models page explains each one.
Language and time
Section titled “Language and time”| Key | Type | Default | Meaning |
|---|---|---|---|
locale |
"en" or "zh-TW" |
"en" |
The language of the text the bot shows in Discord. |
timeZone |
string | "UTC" |
The IANA time zone that schedules and time stamps use. |
See Language and time.
Access
Section titled “Access”| Key | Type | Default | Meaning |
|---|---|---|---|
access.owners |
list of { name, pronouns?, principal?, identities? }, required |
none | The people who run this host. The first is the primary owner and needs a principal, their principal id (their Discord user id works); with Discord they also need a discord:<user id> identity. pronouns is "he", "she", or "they" (default "they"): how prompts refer back to the owner. |
access.admins, access.members |
{ identities?, roles?, everyone? } |
none | Who holds the tier. identities are <provider>:<subject> strings such as discord:<user id>. roles are written <surface>:role:<name>, such as discord:role:<role id>. everyone is true for every surface, or a list of surfaces. |
access.provisioning |
"admitted", "linked", or an object of those by surface |
"admitted" |
admitted: someone the rules admit gets a principal at their first message. linked: only identities linked with roundtable principal link, and the owners’ configured ones, are served. In an object, a surface left out is linked. |
access.backgroundStaleDays |
integer from 1 to 36500 | 30 |
How many days someone whose tier comes only from the rules may go unseen before their background turns are refused. |
access.selfLink.providers |
list of strings | none | Identity providers, such as ["discord"], whose accounts people may link to their own principal through a plugin. |
owner, speakers |
the 0.8 forms | none | Deprecated: owner: { id, name, pronouns? } and speakers: { admins?, members? } by Discord user and role ids. They still work with a warning, but never together with access; roundtable upgrade rewrites them. |
background.perPrincipal |
{ schedules?, delegations? } |
none | Each person’s limits across all their conversations: how many schedules they may keep (1 to 10000) and how many delegations run at once (1 to 1000). Left out, only each conversation’s own limit applies. |
toolTiers |
object of "owner", "admin", or "member" by tool name |
{} |
The lowest tier that may use each named tool. It overrides what the core and plugins chose. |
prompts.shared |
string, required inside prompts |
the prompt bundled with the package | The path of the file that starts every agent’s prompt. Read once at start. |
prompts.guest |
string | a guest prompt bundled with the package | The path of the file that replaces the shared prompt for speakers other than the owner. |
With no admins or members, only the owners can talk to the agents.
See Access tiers.
Agents and avatars
Section titled “Agents and avatars”| Key | Type | Default | Meaning |
|---|---|---|---|
agents |
list of { name, displayName, prompt, character?, channelId? } |
[] |
The first team, created once. An agent that is already stored is never overwritten, so edit agents in Discord afterwards. Without Discord a seed has no channelId. |
coordinator |
string | the first of agents |
Without Discord or discord.guild, the agent the owner’s general requests come to; it must be one of agents and cannot be archived. With discord.guild it is an error, because the agent in discord.entryChannel coordinates. |
team.id |
string | the discord.guild id, else local |
The id the team’s rows (agents, groups, skills, prompts, presets) are stored under, independent of the Discord guild. Set it once and keep it. |
team.formerIds |
string[] | none | The ids the team was stored under before, such as a guild it left. At every boot their rows move to the team’s id (a row the team already holds stays), and without Discord channels the moved agents and groups lose the channel ids they carried, so nothing posts to a deleted channel. |
characters.skins |
list of exactly 6 #rrggbb colors |
the six the package ships | The skin tones every agent is drawn with, picked by a look’s skin index (0 to 5): in the web console, its round table and the agents’ Discord pictures. EAST_ASIAN_SKINS from pi-roundtable/characters is a ready set of light East Asian tones. Agents keep their stored index, so they take the new tones with no migration. A list of another length or a bad color stops the start. |
characters.refreshAvatars |
boolean | false |
Render every agent’s Discord picture again each time the agent server starts, with the host’s skins, and set it where it differs from the stored one. Use it so agents nobody saved since a redraw or a characters.skins change catch up with the web console. It runs after the start without holding it back, skips an agent whose picture is unchanged, and logs one summary line (re-rendered, unchanged, failed); one agent’s failure stops nothing. It overwrites an agent that still wears an old hand-drawn picture. |
avatar |
string | a plain bot picture bundled with the package | Deprecated and ignored since 0.23: agents are composed characters. A warning is logged at start when it is set; removed in 1.0. |
http.publicUrl |
string, required with Discord unless agentServer is false |
none | The address that reaches this process from the internet. Discord fetches the avatars from it. |
http.port |
integer from 1 to 65535 | 3000 |
The TCP port the process listens on. |
http.hostname |
string | none | The hostname the listener binds to. |
http.socketPath |
string | none | A unix socket path to listen on instead of a TCP port. When it is set, port and hostname are not used. |
http.socketMode |
integer from 0 to 0o777 |
0o660 |
The socket file’s permission bits. Widen it only for a proxy that runs as another user. |
Without Discord, http is optional: leave it out when no plugin serves HTTP, and the host opens no listener.
The web chat needs it.
Where work lands (routing)
Section titled “Where work lands (routing)”Most of what an agent does starts with a person and ends where that person is: a message is answered in the conversation it came in, a card waits there, a schedule fires in the conversation it was made in. The optional routing key governs only what has no person present: a foreign webhook’s post in an agent’s place, a message_agent call that names no conversation, an agent’s opening task, and the process’s own error reports. Leave routing out and every one lands where it did before the key existed.
The words used here, and in the code:
- Surface: one chat adapter, named by its key prefix:
discord,app(pi-roundtable-web),webchat,line. A host may have several. - Place: an agent’s conversation on one surface: its channel on Discord, its room
<surface>:agent.<name>on a surface that hosts rooms.webstands for the one surface that hosts rooms when exactly one does. - Primary place: the one place where an agent’s unprompted work lands. It is
autounless you name a surface: the agent’s Discord channel when it has one, else its room on the first surface that hosts rooms. - Named place: a host-level destination with a name. The core declares
ops, the error reports; it is a conversation key, or an agent whose primary place it is. - Mirror (reserved): a place that would get a read-only copy of what the agent posts in its primary place. Answerer (reserved): the claim that answers a surface’s conversations. Both have a position in the block and neither is built: setting one stops the start, naming the key. Claim priorities still decide who answers.
| Key | Values | Default | What it routes |
|---|---|---|---|
routing.agents.<name>.primary |
auto, or a surface name |
auto |
The agent’s primary place. "*" instead of a name sets the default of every agent; an agent’s own key wins, key by key. A name applies to an agent created later too. |
routing.agents.<name>.integration |
origin, primary, or a surface name |
origin |
Where the report turn of a foreign webhook’s post in the agent’s channel runs. The post itself stays where it was posted; the turn names the place it came from. If the destination has vanished, the turn runs where the post was made, with a warning, and is never dropped. |
routing.agents.<name>.agentMessage |
origin-surface, latest, primary, or a surface name |
origin-surface |
The conversation message_agent reaches when the call names none. origin-surface is the agent’s place on the sender’s surface (its room from a room, its Discord channel from Discord), else its primary place, which is logged. latest is the one the agent last ran a turn in, but only on the sender’s surface, else as origin-surface. primary pins messages to the primary place, even from a room into Discord. Naming a conversation in the call beats every rule. |
routing.agents.<name>.opening |
origin-surface, primary |
origin-surface |
Where an agent’s opening task (agent_create’s task) runs: the agent’s place on the surface the creation came from, else its primary place; or always its primary place. |
routing.agents.<name>.mirror |
list of surface names | none | Reserved; a non-empty list stops the start. |
routing.places.ops |
"<surface>:<id>", or { agent } |
none | Where the process’s own errors are reported, as ops.conversation and ops.agent did. The agent form lands in the agent’s primary place and needs the agent server, not Discord. The top-level ops is a deprecated alias that goes away in 1.0; set only one of them. |
routing.surfaces.<name>.agentPlaces |
all |
all |
Whether every agent has a place on the surface, which every surface does today. none is reserved and stops the start. |
routing.surfaces.<name>.answeredBy |
claim name | none | Reserved; setting it stops the start. |
Alerts handled in the web app, with the raw posts left in Discord: Infra’s primary place is its web room, its webhook reports run there, and the host’s error reports land there too. The other agents keep Discord.
routing: { agents: { infra: { primary: "app", integration: "primary" } }, places: { ops: { agent: "infra" } },},A host that is not built around Discord, such as a support desk with LINE customers and Slack, can route every agent into web rooms and name conversations for the rest:
routing: { agents: { "*": { primary: "app" }, triage: { integration: "primary", agentMessage: "primary" }, }, places: { ops: "slack:C0OPS" },},Every mistake stops the start with a ConfigError naming the key and the fix:
- a surface that no plugin registered, or that holds no agent places (a surface that hosts no rooms, or
discordwhere the agents have no Discord channels), named byprimary,integrationoragentMessage; the message lists the registered surfaces. This is checked after every plugin has registered its own; - a value that belongs to another key, such as
latestforintegrationororiginforagentMessage; - an agent key that is not an agent name or
"*", and aplacesname nobody declares (the declared names are listed); - a place that is neither a conversation key
<surface>:<id>nor{ agent }; - the top-level
opsset together withrouting.places.ops; routing.agents,routing.surfacesor an agent place on a host that runs no agent server;- the reserved keys above.
An agent the rules name that the team does not have yet is only a warning in the log: its rules apply once it exists. Code reads the table through AGENTS.routes (primary, placeOn, of, place).
Addons and operations
Section titled “Addons and operations”| Key | Type | Default | Meaning |
|---|---|---|---|
skills |
false, or { builtinDir?, reposDir?, packages? } |
on, with builtinDir the skills bundled with the package and reposDir set to <dataDir>/repos |
false leaves the skills addon out: agents carry no skills and no skill tools exist. Stored skills stay in their tables. packages lists npm packages the host installed: every skill in their pi.skills folders is offered, read-only, and carried and grouped like any other. Startup fails with a message naming the fix when a package is missing, ships no skills, or holds a skill whose name another skill already has. |
memory |
boolean | true |
false leaves the memory addon out: no memory tools and no memory prompt block. The table stays as it is. |
ops.agent |
string | none | Deprecated alias of routing.places.ops: { agent }, going away in 1.0. The name of the agent that investigates the process’s own errors. Needs Discord. |
ops.conversation |
string | none | Deprecated alias of routing.places.ops: "<surface>:<id>", going away in 1.0. Instead of an agent, the key of a conversation the errors are reported to. A chat surface must serve it, a plugin’s claim that takes background turns must own it, and a plugin must contribute the owner background target (the agent server does, with Discord), or the host does not start; the web chat takes no error reports. Set one of ops.agent and ops.conversation. |
drainSeconds |
integer from 1 to 3600 | 180 |
How many seconds a shutdown waits for running turns before it stops them. Give the service manager a stop timeout a minute longer, such as systemd’s TimeoutStopSec. |
interimText |
"on" or "off" |
"on" |
Whether a turn posts the text it writes before its final answer as it goes. "off" posts only the final reply. |
interimPrimaryChars |
integer from 1 to 100000 | 400 |
An intermediate text this long or longer is posted as an ordinary message; shorter narration goes into one small progress message. |
plugins |
list of plugin objects | [] |
Your plugins. They start in the order listed, after the built-in ones. |
With ops.agent (or an agent in routing.places.ops) set, each error and fatal log entry is reported to that agent as a message and a report turn in its primary place; with ops.conversation (or a conversation key in routing.places.ops), to that conversation, whose claim answers the report turn.
The same error goes at most once an hour, and at most five reports go out per hour.
A webhook’s post in an agent’s channel, such as a CI bot’s notice, starts a report turn for that agent with the post’s text, in that channel unless routing sends it to the agent’s primary place. A post that is only an embed counts too: its title, description, fields, footer and link are read as plain text, at most 4,000 characters, so an alert that arrives with no message text is still answered.
For what the addons add and how plugins start, see Services and addons.