Skip to content

Configuration: dashboard, mesh and optional layers ​

This page lists every agentx.json setting for the dashboard, the mesh (other AgentX machines), voices, screen capture and the optional layers: business, boards, the intent graph and typed decisions. For the other sections, see the Configuration reference.

Each table gives the key, the kind of value it takes (its type), the value used when you leave it out (its default), and what it does. "required" means the file is rejected without it. A <id> in a heading is a name you choose.

dashboard ​

The dashboard is the web page served by agentx board serve. See Dashboard.

KeyTypeDefaultWhat it does
dashboard.enabledbooleanfalseTurns the dashboard server on.
dashboard.portnumber4202Port the dashboard listens on.
dashboard.bindstring"127.0.0.1"Address the dashboard listens on. Keep it local unless a reverse proxy sits in front (your own address).
dashboard.tokenstring—Bearer token required for changes made through the dashboard and for its admin data, such as the Cost and Ledger pages' spend and budgets, the errors, checks and live log in Settings › Diagnostics, and the Activity map. Pages served by the dashboard send it for you. For live views, the page swaps it for a pass that works for one minute, so the token itself never goes in a web address. Unset means no token is needed.
dashboard.daemonUrlstring"http://localhost:18800"The main daemon the dashboard reads live data from.
dashboard.daemonslist of objects[]Extra daemons to show, beyond the peers the main daemon already knows.
dashboard.draftAgentstring—Agent that drafts text when you create an issue from a board.
dashboard.wall.rhythmHoursnumberrequests.staleAfterHoursThe normal rhythm of work on the Hub, in hours. An open task with no move for more than twice this is stalled.
dashboard.wall.projectslist of objects[]Names the Hub's projects. A task's project comes from its home repo, its agent, or that agent's workspace, checked in that order. Empty: a task's project is its home repo.
dashboard.wall.capacity.thresholdwhole number—Flags an agent over capacity on the Hub when its tasks in progress plus the tasks waiting on it are above this. Unset: no flag.

Each entry in dashboard.daemons:

KeyTypeDefaultWhat it does
namestringrequiredLabel shown for that daemon.
urlstringrequiredThat daemon's HTTP address.
dashboardUrlstring—That machine's dashboard address, used to pass settings changes through. Defaults to url with the port changed to 4202.
tokenstring—Bearer token for that daemon's API.
dashboardTokenstring—Bearer token for that machine's dashboard. Defaults to token.

Each entry in dashboard.wall.projects:

KeyTypeDefaultWhat it does
namestringrequiredThe project's name on the Hub.
reposlist of strings[]Home repos in this project, as group/project. Case does not matter.
agentslist of strings[]Agents whose tasks are in this project.
workspaceslist of strings[]Folders: an agent whose workspace is one of them, or inside one, is in this project. ~/ is your home folder.
rhythmHoursnumberdashboard.wall.rhythmHoursThis project's own normal rhythm, in hours.
budget.monthlyUsdnumber (0–1000000)unset (no cap)Most this project's runs may spend in one calendar month (UTC), in US dollars. At the cap, new runs for the project are refused until the month ends or you raise it. Applies on save. See Cap a project.
budget.warnRationumber (above 0, up to 1)0.8Share of budget.monthlyUsd at which you get one notice for the month.

When two entries name the same repo or agent, the first one wins.

mesh ​

The mesh links several AgentX machines so their agents can reach each other. See Add a second machine.

KeyTypeDefaultWhat it does
mesh.enabledbooleanfalseTurns the mesh on.
mesh.peerslist of objects[]The other machines this one talks to.
mesh.inboxeslist of objects[]Named inboxes that other machines may send work to. None are published until you add one.
mesh.discovery"static" | "mdns""static"How peers are found. Only static (the mesh.peers list) is used today.
mesh.healthCheck.intervalnumber60Seconds between checks that each peer is up.
mesh.healthCheck.timeoutnumber10Seconds to wait for a peer before counting it as down.
mesh.feed.enabledbooleantrueFollow the events of every reachable peer and show them in this machine's event feed. See Events from other machines.
mesh.feed.skipTypeslist of strings["task:step"]Event types peers leave out of the feed they send this machine. The default skips per-step agent activity. A change applies when this machine next reconnects to each peer.
mesh.delegation.asyncWhenHumanbooleantrueWhen a person started the conversation, an agent that asks another agent gets its answer later, as a new message, instead of waiting. See When an agent asks another agent. Applies without the mesh too.
mesh.delegation.timeoutMinutesnumber30Minutes a helper agent has to answer before the asking agent is told it timed out. From 1 to 240.
mesh.delegation.requeueRelayOnRestartbooleantrueIf a restart stops your agent while it is passing a helper's answer on to you, your agent tries once more after the restart. If that try fails too, you get a short message saying the answer did not come through, and your open request is marked as needing attention. Turn it off (false) to skip the second try.
mesh.delegation.callbackSendsbooleantrueAn agent's agentx_send_agent that no person waits on comes back to it: the answer, failure or timeout arrives as a new message in the chat it sent from, and a message the other agent writes back lands there too. See When an agent asks another agent. Off: such sends are only queued.
mesh.delegation.coalesceSecondsnumber120When an agent asked several other agents from one chat, a finished answer waits this many seconds for the others still running, so the asking agent gets them all in one new message instead of one each. From 0 to 900. 0 joins only answers that are already in. See When an agent asks another agent.
mesh.delegation.agentChains.perAgentHournumber15Hand-offs one agent may start in a rolling hour for work no person started (a schedule, an agent's own chat, agents asking each other). Past it the hop is refused with 409 and the agent is told to finish the work itself or write to the owner once. Work a person started is never counted. 0 turns it off. See When an agent asks another agent.
mesh.delegation.agentChains.perChainDaynumber40Hand-offs one chain (the same root, across agents and machines) may make in a rolling 24 hours, with no person behind it. 0 turns it off. Counts live in memory and start over on restart.

Each entry in mesh.peers:

KeyTypeDefaultWhat it does
urlstringrequiredThe peer's daemon address.
namestringrequiredThe peer's name.
tokenstring—Bearer token sent to that peer. Use an ${ENV_VAR} reference.

Guest meshes (another organisation let into part of this one) are not in agentx.json: the host keeps its grants in .agentx/guests.json and their trail in .agentx/guests-log.jsonl; the guest keeps the hosts it joined in .agentx/guest-hosts.json. All three are readable by your user only. See Let another organisation into part of your mesh.

Each entry in mesh.inboxes:

KeyTypeDefaultWhat it does
namestringrequiredInbox name other machines see.
agentstringrequiredLocal agent that handles it. Not shown to other machines.
enabledbooleantrueWhether the inbox accepts work.

events ​

The daemon keeps its most recent events in memory so a late reader can catch up. See Events.

KeyTypeDefaultWhat it does
events.ringSizenumber1000How many recent events GET /events/recent can return. Older ones are dropped. Nothing is written to disk.

voice and meshVoices ​

How agents speak aloud. See AgentX Voice.

KeyTypeDefaultWhat it does
voice.provider"system" | "elevenlabs""system"Speech engine: the free system voices, or ElevenLabs.
voice.fallback"system" | "none""system"What happens when ElevenLabs cannot speak: use the system voice, or stay silent.
voice.systemstring or map of strings—System voice for agents without their own. A name, "system" for the OS default, or one per language such as { "en": "Samantha", "fr": "Thomas" }. Unset gives each agent its own.
voice.localestring"en"Language used when voices are assigned, for example "fr-FR".
voice.listenerstring—What agents call you, for example a first name. Unset means "the user".
voice.pronunciationslist[]How a word is said aloud without changing how it is written. Each entry is { "written": "Okafor", "spoken": "Oh-kah-for" }, with an optional "languages" list ("en", "fr", "ar") that limits it to lines in those languages. The written form matches whole words, without case. At most 200. See Say a word the way it is said.
voice.pointerbooleantrueDraw the agent's pointer and name tag on screen during a lesson. false never draws it; a lesson is then spoken only. A plain spoken answer never shows it.

meshVoices.<agent> sets the voice of an agent that runs on another machine, keyed by that agent's id. This machine speaks for it, so the other machine needs no ElevenLabs key. Unset fields come from the agent's card.

KeyTypeDefaultWhat it does
namestring—What to call the agent aloud.
provider"system" | "elevenlabs"—Speech engine for this agent. Overrides voice.provider.
systemstring or map of strings—System voice for this agent, as in voice.system.
elevenlabsVoiceIdstring—ElevenLabs voice to use.
gender"female" | "male" | "neutral"—Used to pick a matching voice when none is set.
stylestring—A few words on manner, for example "calm, brief".
introstring—One-line self-introduction used on first contact.
narrate"off" | "on" | "all"—Speak short updates from the agent's steps while it works. on skips scheduled jobs; all includes them.

screen ​

How agents capture the screen. See Capture the screen at the right moment.

KeyTypeDefaultWhat it does
screen.maxPixelsnumber1200000Pixel budget for one capture. Larger captures are scaled down.
screen.timeoutMsnumber5000Longest a capture waits for a change or for the screen to settle, in milliseconds.
screen.intervalMsnumber100Time between samples while waiting, in milliseconds.
screen.changeThresholdnumber (0–1)0.015Average difference above which two samples count as different.
screen.stableMsnumber400How long a region must stay unchanged to count as settled, in milliseconds.
screen.regionsmap of objects{}Named parts of the screen, in screen points. A name here replaces a built-in region of the same name.
screen.buffer.enabledbooleanfalseKeeps the last few seconds of a region in memory. Frames are written out only when asked for.
screen.buffer.secondsnumber (up to 120)10How many seconds the buffer keeps.
screen.buffer.fpsnumber (up to 10)2Frames per second kept in the buffer.
screen.buffer.regionstring"screen"Region the buffer records.
screen.buffer.maxPixelsnumber300000Pixel budget for one buffered frame.

Each entry in screen.regions (for example "chat": { "x": 0, "y": 0, "width": 400, "height": 300 }):

KeyTypeDefaultWhat it does
x, ynumberrequiredTop-left corner.
width, heightnumberrequiredSize of the region.

business ​

An experimental layer that runs agents like a team, with roles, working hours and a shared pool of work. It is off by default and its shape may change between minor versions. The whole business block is optional. An org chart alone (the Hub's Org page) needs only business.orgChart; business.mainChannel is required once business.enabled is on.

KeyTypeDefaultWhat it does
business.enabledbooleanfalseTurns the business layer on.
business.timezonestring"UTC"Timezone for working hours.
business.mainChannelobjectrequired when enabledChat where the team posts reports and "no plan today" notices: channel, chatId and optional accountId.
business.mainChannel.accountIdstring—Which account of that channel to post from.
business.workSourceobject{ "type": "backlog" }Where agents find work. type is "backlog", "gitlab" or "wiki".
business.workSource.pathstring".agentx/backlog.md" for backlogThe backlog file (backlog), or the folder to read (wiki, required there).
business.workSource.projectslist of strings[]GitLab projects to read (gitlab). Empty means all configured GitLab projects.
business.workSource.globstring"**/*.md"Which files to read in the folder (wiki).
business.rolesmap of objects{}Job roles, keyed by role id.
business.orgChartmap of objects{}Which agent holds which role and when it works, keyed by agent id.
business.relationslist of objects[]Typed links between org members, people included. See below.
business.orgPeoplemap of objects{}People placed in the org chart, keyed by an id from people, each with an optional role (a role id from business.roles). A person named in business.relations is in the chart without an entry here. Set from Edit the org chart on /org.
business.departmentsmap of objects{}Named groups of org members, keyed by department id: an optional name (the id when unset), an optional head and members, written like relations (agent:<id>, person:<id>). A member is in one department at most. They group cards on the chart and change no reporting line. See Group members into a department.
business.projectslist of objects[]Projects, with an optional project manager, client, name, lead and team. See See who runs each project.
business.contactMaplist of objects[]Maps a chat or sender to a client and project, so the activity view credits the right client.
business.clientsmap of objects{}Per-client overrides, keyed by client id. Clients are otherwise worked out from projects and contactMap.
business.workTickMinutesnumber (1–60)15How often, in minutes during working hours, agents are asked to pick up work.
business.idleQueueThresholdnumber0Accepted but not read by the daemon yet.
business.standup.enabledbooleantrueRuns the morning standup. When off, it does nothing.
business.standup.plansDirstring".agentx/plans"Folder holding the day's plan (<date>.md, falling back to the week, then the month). With no plan, the standup posts a notice and starts no agent.
business.standup.maxAgentsPerDaynumber (1–100)20Most agents the standup may start in one morning.
business.standup.dryRunbooleanfalsePosts the day's plan for review but starts no agent.

Each entry in business.roles.<role>:

KeyTypeDefaultWhat it does
titlestringrequiredRole name given to the agent.
responsibilitieslist of strings[]Listed in the agent's instructions.
sopPathstring—File with the role's standard procedure, referenced in the agent's instructions.
kpislist of strings[]Measures of success for the role.

Each entry in business.orgChart.<agent>:

KeyTypeDefaultWhat it does
rolestringrequiredRole id from business.roles.
reportsTostring—The manager: another agent in the org chart (its id, or agent:<id>), or a person from people as person:<id>. Read as a reports-to relation.
schedule.dayslist of "mon"…"sun"Monday to FridayWorking days.
schedule.start, schedule.endstring HH:MMrequiredStart and end of the working day.
schedule.lunchobject—Lunch break, with start and end as HH:MM.
utilizationTargetnumber (0–1)0.8Share of working time the agent should be busy.

Each entry in business.relations links two members. A member is agent:<id> (an agent in business.orgChart), person:<id> (a person in people), or agent:<node>/<id> (an agent on the mesh peer named <node> in mesh.peers: shown on the chart, never sent work); a bare id is an agent. An unknown member stops the business layer from starting, with an error that names it. A line to a node not in mesh.peers (a peer removed or renamed) is left out instead: the daemon still starts, logs the line, and the Org page names the problem. Saving such a ref from the Hub or the CLI is refused. Whether the node hosts that agent is not checked at start; the Org page shows it.

KeyTypeDefaultWhat it does
fromstringrequiredThe member the relation starts from.
tostringrequiredThe member it points to.
type"reports-to", "dotted-line" or "acts-for"requiredreports-to: the line manager. At most one per member, no cycles, and escalation follows it; it stops at a person, who is never sent a task. dotted-line: a second manager for one topic or project; many allowed, never used for escalation. acts-for: an agent works on behalf of a person; from an agent to a person only.

For example, an agent that reports to an agent, with a dotted line to the owner, working on the owner's behalf:

json
"people": [{ "id": "owner", "name": "The Owner", "role": "owner" }],
"business": {
  "orgChart": { "pm": { "role": "pm" }, "dev": { "role": "dev", "reportsTo": "pm" } },
  "relations": [
    { "from": "pm", "to": "person:owner", "type": "reports-to" },
    { "from": "dev", "to": "person:owner", "type": "dotted-line" },
    { "from": "agent:dev", "to": "person:owner", "type": "acts-for" }
  ]
}

GET /api/admin/org returns people (id and name), and relations with every member written in full, orgChart reportsTo included.

When you add an org chart entry from the dashboard or with agentx business orgchart add, its reportsTo is checked against the rules above. A wrong value is refused with the same message the daemon would show at start, and agentx.json is not changed. Lists and agent prompts show a person boss by their name from people.

Each entry in business.projects:

KeyTypeDefaultWhat it does
idstringrequiredProject id, for example group/project.
pmstring—Agent id of the project manager.
clientstring—Client the project belongs to. Defaults to the part of id before the first /.
namestringthe idName shown on the Org page's Projects view.
leadstring—The person who leads the project, person:<id>. A bare id is read as a person. Shown on the Org page only; pm stays the agent.
teamlist of strings—Who works on the project: agent:<id> of an agent in business.orgChart, person:<id>, or a bare agent id. Shown on the Org page only; one member can be on several projects.

Each entry in business.contactMap (the first match wins: chatId, then username, then channel):

KeyTypeDefaultWhat it does
clientstringrequiredClient this contact belongs to.
channelstring—Channel kind, for example "telegram".
chatIdstring—The chat's id on that channel.
usernamestring—Sender's username.
senderIdstring—Sender's numeric id, when the username changes.
projectstring<client>/_chatProject the conversation counts toward.
displayNamestring—Name shown for the contact.

Each entry in business.clients.<client>:

KeyTypeDefaultWhat it does
namestringthe client idDisplay name.
kind"client" | "internal" | "own"—client is someone waiting on you; own is your own product; internal has no outside deadline.
respondWithinstring—How long a wait may last before it matters, such as "4h", "90m" or "2d". Unset means no deadline.
standinglist of strings[]What agents may do for this client without asking; "*" means everything. Ignored when kind is client.

boards ​

Kanban boards backed by GitLab issues, shown on the dashboard's Boards page. boards is a list; each board has these keys:

KeyTypeDefaultWhat it does
idstringrequiredBoard id: lowercase letters, digits, - or _.
namestringrequiredBoard title.
source.type"gitlab"requiredWhere issues come from. Only GitLab today.
source.projectslist of stringsrequiredGitLab project paths. At least one.
primaryToolLabelstring—A label every card must carry; shown as a fixed filter chip.
labelslist of objects[]Labels offered when you create or edit a card.
columnslist of objectssix columnsThe columns. The default is Open, To Do, Doing, On Hold, Review and Closed, driven by Status:: scoped labels.
timeRangeDaysnumber (1–365)30How many days of open issues to show.
closedWindowDaysnumber (1–365)30How many days of closed issues the Closed column shows.
reconciliationobject{}Settings for flagging stale cards, listed below.
reconciliation.enabledbooleantrueAccepted but not acted on yet: flagging cards left in Doing too long.
reconciliation.staleDoingMinutesnumber45Accepted but not acted on yet.
reconciliation.respectLunchBreakbooleantrueAccepted but not acted on yet.
reconciliation.respectSchedulebooleantrueAccepted but not acted on yet.
reconciliation.action"badge" | "notify""badge"Accepted but not acted on yet.

Each entry in labels:

KeyTypeDefaultWhat it does
namestringrequiredThe GitLab label, used as written.
colorstring #rrggbb"#6366f1"Label colour.
descriptionstring—Label description.

Each entry in columns:

KeyTypeDefaultWhat it does
idstringrequiredColumn id: lowercase letters, digits, - or _.
titlestringrequiredColumn heading.
kind"open-backlog" | "scoped-label" | "closed" | "label""label"Which issues land here. open-backlog: open issues with no status label. scoped-label: open issues with scopedLabel. closed: closed issues; dragging here closes, dragging out reopens. label: open issues with mapsToLabel.
mapsToLabelstring—For label columns: label added on entry and removed on exit.
scopedLabelstring—For scoped-label columns: the full label, such as Status::Doing.
scopedPrefixstring"Status"For open-backlog columns: issues with a label of this prefix are left out.
accentstring—Colour of the column's top bar.

graph ​

The intent graph sorts requests into a fixed tree of topics and helps wiki search. It is off by default.

When a request is not already in the graph's cache, the classifier asks the intent-path decision seat first if that seat is active under decisions.seats, and only falls back to graph.classifierModel when the seat has no confident answer. When the seat is sure of the category but only somewhat sure of the verb (the specific kind of work), it files the request under the category alone instead of guessing a verb. The seat chooses the category from a short description of each one (for example, support is a person talking to an agent, and social is content made for an audience), so a greeting or a complaint is not filed as a post or a settings change. In shadow the model still decides and the seat's answer is recorded next to it, so agentx decisions stats shows how often the two agree before the seat takes over. The path a request was filed under also steers the wiki: while that request runs, agentx_wiki_query asks the daemon for its path and ranks the articles that match the question by how much of the path they share, weighted by graph.retrievalWeights.graph. A query sent before the request is classified, or from outside a running request, searches without a path.

KeyTypeDefaultWhat it does
graph.enabledbooleanfalseTurns the intent graph on.
graph.baseDirstring".agentx/graph"Folder holding the graph's files.
graph.draftAgentstring—Agent that proposes classifications. Falls back to dashboard.draftAgent.
graph.reviewAgentstring—Agent agentx graph review uses to approve or reject pending classifications. Falls back to graph.draftAgent.
graph.autoApproveStructure"strict" | "extend-leaves" | "any""extend-leaves"Which classifications skip review. strict: none. extend-leaves: those that reuse existing topics or add one new topic at the deepest level. any: all.
graph.autoApproveConfidencenumber (0–1)1Classifications at or above this confidence also skip review. 1 turns this off.
graph.classifierModelstring"claude-haiku-4-5-20251001"Model used to classify.
graph.retrievalWeights.graphnumber0.6Weight of topic match in wiki search.
graph.retrievalWeights.bm25number0.4Weight of text match in wiki search.

wiki ​

The wiki as seen from its pages. See Wiki › Ask an agent to curate a page.

KeyTypeDefaultWhat it does
wiki.curator.enabledbooleantrueShows the chat button on every wiki page in the dashboard. Off, the button is hidden and curator requests are refused.
wiki.curator.agentstring—Agent that answers on every page. Unset, the page's owner agent answers.

quality ​

Gates that check agent pull requests before they merge. Each one is off by default. See Have a second agent review pull requests.

KeyTypeDefaultWhat it does
quality.reviewGate.enabledbooleanfalseA different agent reviews each agent pull request against its linked issue and posts the agentx/review status.
quality.reviewGate.mode"advisory" or "required""advisory"Advisory marks the status "[advisory]". Required blocks merges once agentx/review is a required check on GitHub.
quality.reviewGate.reviewer.agentstring—The reviewing agent. Must not be the pull request's author.
quality.reviewGate.reviewer.modelstringthe agent's modelModel for reviews; pick one other than the author's.
quality.reviewGate.pathsstring[][]Only review pull requests that change a matching file. Empty: all.
quality.reviewGate.maxCostPerReviewnumber2US dollars; a dearer review ends as error. 0: no limit.
quality.reviewGate.maxMinutesnumber10A longer review is stopped and ends as error.
quality.reviewGate.maxReviewsPerPrPerDaynumber6Most reviews of one pull request in 24 hours; past it the status is error. 0: no limit.
quality.reviewGate.ciWaitMinutesnumber5How long to wait for other checks before reviewing.
quality.reviewGate.maxDiffKbnumber256A longer diff is cut, and the reviewer is told.
quality.reviewGate.forgesstring[]["github"]Where the gate reviews: "github" pull requests, "gitlab" merge requests, or both. See On GitLab merge requests.
quality.reviewGate.testsobject{}Per "owner/repo": checkout (local clone), command (shell) and timeoutMinutes (15). Runs the tests on agent pull requests before the review and posts agentx/tests. See Run the project's tests before the review.
quality.mergePolicy.enabledbooleanfalsePosts the agentx/merge-policy status on every pull request: core paths need a person's approval. See Let agents merge only edge changes.
quality.mergePolicy.mode"advisory" or "required""advisory"Advisory marks an unapproved core change "[advisory]" and passes it. Required leaves it pending until a person approves.
quality.mergePolicy.corePathsstring[][]Core files, as patterns. Empty: nothing is core.
quality.mergePolicy.edgePathsstring[][]Exceptions inside core folders that count as edge.
quality.mergePolicy.labelstring"core-change"Label put on a pull request that changes a core path.
quality.mergePolicy.approversstring[][]GitHub logins whose reviews count. Empty: owners, members and collaborators, except the author and AgentX's own accounts.
quality.mergePolicy.ownerCardbooleantrueIn required mode, ask the owner on an approvals card; YES approves that commit.

decisions ​

Typed decisions ("seats") let a small, fast model answer fixed-choice questions with a probability. Everything is off by default. See Jev and typed decisions.

KeyTypeDefaultWhat it does
decisions.enabledbooleanfalseTurns typed decisions on.
decisions.dbPathstring".agentx/decisions/decisions.sqlite"Database where every decision is recorded.
decisions.redactStatebooleanfalseStores only a fingerprint of each decision's input, not its text. You can no longer replay decisions offline.
decisions.keepStateRowsnumber2000How many recent inputs to keep in full per seat; older ones keep only the fingerprint.
decisions.defaultBackendstring"local"Backend used by seats that don't name one.
decisions.backendsobject{}Settings for each backend below.
decisions.seatsmap of objects{}Per-seat settings, keyed by seat name.
decisions.routingobject{}Models to move simple tasks down to, and hard tasks up to.
decisions.routing.cheapModelstring—Cheaper model for claude-code agents (older form of the next key).
decisions.routing.cheapModelsobject—Cheaper model per engine.
decisions.routing.cheapModels.claude-codestring—Cheaper model for claude-code agents, such as a claude- model or haiku.
decisions.routing.cheapModels.codex-clistring—Cheaper model for codex-cli agents, such as a gpt- model.
decisions.routing.edgeModelsobject—Most capable model per engine. A task the task-edge decision is sure needs it runs on this model; the next task is back on the agent's own model. See Edge model and sub-agents.
decisions.routing.edgeModels.claude-codestring—Most capable model for claude-code agents, such as a claude- model or fable.
decisions.routing.edgeModels.codex-clistring—Most capable model for codex-cli agents, such as a gpt- model.
decisions.routing.impliedWorkoff | shadow | activeoffHow a message that describes a problem and asks for nothing is handled, when a person wrote it and the task-edge seat is on. shadow records and logs what it would do. active asks the agent to state the job before doing it, and moves the task to the edge model when the problem needs a design change. See Messages that describe a problem and ask for nothing.

Local backend (asks a model through an agent engine):

KeyTypeDefaultWhat it does
decisions.backends.localobject{}The local backend.
decisions.backends.local.providerstring"claude-code"Engine used to ask.
decisions.backends.local.modelstring"claude-haiku-4-5-20251001"Model used to ask.
decisions.backends.local.structureMode"auto" | "tool" | "text""auto"How the answer's shape is enforced: a forced tool call, JSON in text, or whichever the engine supports.
decisions.backends.local.normalizeProbabilitiesbooleantrueRescales the model's probabilities so they add up to 1.
decisions.backends.local.nRetryMalformedStructurenumber (0–3)1Retries when the answer has the wrong shape.
decisions.backends.local.maxStateCharsnumber24000Longest input sent, in characters.

simple-jev backend (a self-hosted server that reads the model's own probabilities):

KeyTypeDefaultWhat it does
decisions.backends.simpleJevobject{}The simple-jev backend.
decisions.backends.simpleJev.baseUrlstring"http://127.0.0.1:8000/v1"Server address.
decisions.backends.simpleJev.modelstring—Model to use.
decisions.backends.simpleJev.apiKeyEnvstring—Name of the environment variable holding the key.
decisions.backends.simpleJev.timeoutMsnumber30000Request time limit, in milliseconds.
decisions.backends.simpleJev.maxStateCharsnumber6000Longest input sent, in characters.
decisions.backends.simpleJev.maxChoiceOptionsnumber (2–255)50Most options one question may have.

jev backend (Jev through OpenRouter) and typesafe backend (Jev direct from TypeSafe):

KeyTypeDefault (jev)Default (typesafe)What it does
decisions.backends.jev.baseUrl, decisions.backends.typesafe.baseUrlstring"https://openrouter.ai/api/alpha""https://api.typesafe.ai/v1"Service address.
decisions.backends.jev.path, decisions.backends.typesafe.pathstring"/decisions""/systemone"Endpoint path.
decisions.backends.jev.model, decisions.backends.typesafe.modelstring"jev-latest""jev-latest"Model id.
decisions.backends.jev.apiKeyEnv, decisions.backends.typesafe.apiKeyEnvstring"OPENROUTER_API_KEY""TYPESAFE_API_KEY"Name of the environment variable holding the key.
decisions.backends.jev.timeoutMs, decisions.backends.typesafe.timeoutMsnumber3000030000Request time limit, in milliseconds.
decisions.backends.jev.maxStateChars, decisions.backends.typesafe.maxStateCharsnumber9000090000Longest input sent, in characters.
decisions.backends.jev.maxChoiceOptions, decisions.backends.typesafe.maxChoiceOptionsnumber (2–255)255255Most options one question may have.

Each entry in decisions.seats.<seat>:

KeyTypeDefaultWhat it does
mode"off" | "shadow" | "active""off"off: unused. shadow: runs and records only. active: its answer is used.
backendstringdecisions.defaultBackendBackend for this seat.
modelstring—Model for this seat.
timeoutMsnumber10000Time limit per decision, in milliseconds. request-gate and request-context default to 3000 instead, because a message waits for them; a value you set is used, but a message never waits more than 5 seconds for either.
temperaturenumber1Calibration fitted from labelled answers (agentx decisions calibrate). 1 means not calibrated yet.
explorenumber (0–1)0.15Share of would-be skips run anyway, so the seat can still be graded.
holdoutnumber (0–1)—Share of turns that skip the seat as a comparison group. Only seats that run an experiment read it.
json
"decisions": {
  "enabled": true,
  "seats": { "request-gate": { "mode": "shadow", "backend": "jev" } }
}

demo ​

How long agentx demo waits while it starts. The demo reads this from the agentx.json in the folder you run it from. It needs no config file, so this is only for machines where it starts slowly.

KeyTypeDefaultWhat it does
demo.startupTimeoutSecondsnumber (1–3600)—Seconds each startup step may take: each node answering /health, the dashboard answering /live (the address the demo prints, which opens the Hub's Live page), the nodes finding each other. Unset: AGENTX_DEMO_STARTUP_TIMEOUT, else 60, raised when the machine is busy (the 1-minute load average above the CPU count), up to 300. The --startup-timeout flag overrides both.

admission ​

The session queue: every new agent session waits until the machine has room. Read it with agentx queue. How it works: Keep a small machine from running out of memory.

KeyDefaultWhat it does
enabledtrueOff: sessions start at once, as before.
mode"enforce""observe" only logs what it would hold.
tiers["claude-code", "codex-cli", "opencode"]Agent tiers that wait in the queue.
maxSessions0Most sessions at once; 0 = one per GB above the first 2 GB, at least 2.
ownerExtraSessions1Owner work may go this many over maxSessions.
delegationHeadroom2Helper runs started by a running session may go this many over maxSessions.
minAvailableMemoryMB512Hold below this free memory…
minAvailableMemoryPercent10…or below this share of the memory, whichever is larger.
maxSwapUsedMB0Hold above this swap in use; 0 = half the swap, or three quarters of the memory where swap grows on demand.
minDiskFreeMB2048Hold below this free disk; 0 = no check.
maxLoadPerCpu2Hold above this one-minute load per processor; 0 = no check.
minStartGapSeconds10Least time between two starts.
boot.windowSeconds300How long the slow start after boot lasts.
boot.startsPerInterval2Starts allowed per interval during it.
boot.intervalSeconds30The interval.
allowOneWhenIdletrueWith nothing running, one session starts even when memory is short.
maxWaitMinutes60Refuse work still waiting after this long, with a plain message; 0 = never.
waitNotice.afterSeconds120One written line to the person whose chat message has waited this long; 0 = off. A desktop assistant request shows Waiting for room after the same wait.
waitNotice.channels["gitlab"]Channels that get the wait line and the plain refusal and plan-limit lines.
sampleSeconds5How often resources are read again while work waits.
classes{}Named limits, e.g. { "browser": { "max": 1, "agents": ["web-tester"] } }.
closeIdle.enabledtrueWhile work waits on memory or swap, close idle sessions early.
closeIdle.maxPerRound3Most sessions closed per round.
closeIdle.minQuietSeconds60Never close a session quiet for less than this.
closeIdle.settleSeconds30Seconds between rounds, so the next reading shows what the last round freed.
priority.ownerChannels["voice", "app"]Channels whose work runs at owner priority.
priority.ownerPeople[]People ids whose work runs at owner priority.
priority.criticalAgents[]Agents whose work runs at critical priority. Critical work (these agents, and messages sent with "priority": "critical") is not held by the swap or load checks; neither is owner work.
priority.backgroundChannels["cron", "heartbeat", "routine"]Channels whose work runs last.

environment ​

What the node reports about itself: read it with agentx node. How it works: Ask the node about its machine and account.

KeyDefaultWhat it does
tools["claude", "codex", "git", "gh", "glab", "node", "pnpm", "npm", "python3", "docker"]Programs whose version the node reads. A name runs <name> --version; { "name": "uv", "command": "uv", "args": ["version"] } runs other arguments.
toolsRefreshHours6How often the versions are read again (0.25–168). They are never read on a request.

mail sender ​

The one sender for mail AgentX itself sends, such as sign-in links (#1478). It is not an agent's mailbox (those are under channels.email): it only sends. It works with any mail provider that accepts SMTP, the usual way to send mail with a login for your sending domain. Unset: AgentX sends no mail of its own.

KeyDefaultWhat it does
mail.sender.kindrequired"smtp".
mail.sender.fromrequiredThe address mail comes from, on the domain your provider sends for, for example no-reply@mg.example.com.
mail.sender.name"AgentX"The sender name people see.
mail.sender.hostrequiredThe provider's SMTP server.
mail.sender.port587SMTP port.
mail.sender.securefalsefalse: upgraded to TLS when the server offers it (port 587). true: TLS from the start (port 465).
mail.sender.userrequiredThe SMTP login. Must be a ${VAR} reference; the value goes in .env.
mail.sender.passwordrequiredThe SMTP password. Must be a ${VAR} reference; the value goes in .env.

Example, with made-up values. In agentx.json:

json
"mail": {
  "sender": {
    "kind": "smtp",
    "from": "no-reply@mg.example.com",
    "name": "Example Wall",
    "host": "smtp.example-mail.net",
    "user": "${AGENTX_MAIL_USER}",
    "password": "${AGENTX_MAIL_PASSWORD}"
  }
}

and in .env, next to agentx.json:

AGENTX_MAIL_USER=postmaster@mg.example.com
AGENTX_MAIL_PASSWORD=your-smtp-password

A login or password written straight into agentx.json is refused when the config loads, so it never ends up in a file that gets copied or shared. In your provider's settings for the sending domain, turn off click tracking and open tracking, so links in the mail stay as AgentX wrote them.

To check the setup, run agentx mail test you@example.com in the folder with agentx.json. It sends one short test mail. See agentx mail test.

wall sign-in ​

Lets a teammate or a client sign in to their page with a link sent by email, instead of a pairing code (#1478). It needs the mail sender too. Without both, the sign-in page says it is not set up. How it works for the person: Let them sign in with their email. The owner can sign in by link too, with full owner rights once each new browser is confirmed in the popup on the home machine: You, the owner, by link.

KeyDefaultWhat it does
wall.signIn.originrequiredThe fixed https:// address people open, without a path, for example https://your-mac.tailnet-name.ts.net. Every mailed link starts with it, whatever address a request came in on.
wall.signIn.firstSignIn"card""card": a person's first sign-in waits for your yes on a decision card. "auto": a member goes straight in. A client always gets the card, and each new owner browser always waits for a yes in the popup on the home machine.
json
"wall": {
  "signIn": { "origin": "https://your-mac.tailnet-name.ts.net", "firstSignIn": "card" }
}

Sign in with an account (Google or another OpenID Connect provider) ​

wall.signIn.oidc adds a Sign in with … button to the same page (#1675). It needs wall.signIn.origin, but not the mail sender. Nothing in AgentX is written for one provider: any OpenID Connect provider works with its own values.

KeyDefaultWhat it does
wall.signIn.oidc.namerequiredThe name on the button, for example "Google".
wall.signIn.oidc.issuerrequiredThe provider's address, without a trailing slash, for example https://accounts.google.com.
wall.signIn.oidc.clientIdrequiredThe OAuth client id.
wall.signIn.oidc.clientSecretrequiredThe client secret, only as a ${VAR} reference. The value goes in .env.
wall.signIn.oidc.hdnoneOnly accounts of this Google Workspace domain.
json
"oidc": {
  "name": "Google",
  "issuer": "https://accounts.google.com",
  "clientId": "${AGENTX_OIDC_CLIENT_ID}",
  "clientSecret": "${AGENTX_OIDC_CLIENT_SECRET}"
}

Put this inside wall.signIn. In the provider's console, make an OAuth client of type Web application with the return address <origin>/member/signin/oidc/done, for example https://your-mac.tailnet-name.ts.net/member/signin/oidc/done. A client secret written straight into agentx.json is refused when the config loads.

Check it worked ​

  1. Terminal: in the folder with agentx.json, run agentx config check. It prints ✓ Config valid.
  2. Terminal: run agentx config get <path> for the key you changed, for example agentx config get mesh.healthCheck.interval. It prints the new value.
  3. Terminal: run agentx daemon status to confirm the daemon is running.

If something is wrong ​

  • config check names a field: fix the value to match the type in the tables above. Ids for boards and columns must be lowercase.
  • Dashboard changes don't show: the dashboard is its own process. Restart it after changing dashboard settings.
  • A script that reads the dashboard's admin data gets 401: with dashboard.token set, every /api/admin/ address needs it. Send the header Authorization: Bearer <your token> with each request.
  • The live log in Settings › Diagnostics or the Activity map stays empty on another computer: sign in at /login on that dashboard first, then reload the page.
  • The config is refused with mail.sender.user or mail.sender.password: put the value in .env: move the value to .env and write the ${VAR} reference in agentx.json, as in the mail sender example.
  • agentx mail test says Not sent: the message after it comes from the provider. Invalid login or 535 means a wrong login or password in .env. A timeout usually means a wrong host or port, or secure doesn't match the port (false for 587, true for 465).
  • The test mail never arrives, but mail test says Sent: look in the spam folder, then check the provider's sending log for that address.
  • A mesh peer shows as down: check its url and token, then raise mesh.healthCheck.timeout if the link is slow.
  • agentx demo says Timed out waiting for …: the machine is too busy for the startup limit. Run it again with --startup-timeout 300, or set demo.startupTimeoutSeconds. The line Startup limit: … at the top shows the value in use and where it came from.
  • A backend key is empty at runtime: the variable named in apiKeyEnv is missing from .env. Add it, then restart the daemon.

Released under the MIT License.