Skip to content

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 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;
Key Type Default Meaning
name string "Roundtable" The assistant’s display name in the text the bot shows.

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.
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.
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.

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.

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.

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.

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. web stands 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 auto unless 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 discord where the agents have no Discord channels), named by primary, integration or agentMessage; 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 latest for integration or origin for agentMessage;
  • an agent key that is not an agent name or "*", and a places name nobody declares (the declared names are listed);
  • a place that is neither a conversation key <surface>:<id> nor { agent };
  • the top-level ops set together with routing.places.ops;
  • routing.agents, routing.surfaces or 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).

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.