Configuration: channels
The channels section of agentx.json turns on the apps your agents talk through: Telegram, WhatsApp, GitLab, GitHub, phone app notifications (push), ntfy and browser calls (WebRTC). This page lists every field. For the other sections, see the Configuration reference; for what each channel does, see Channels.
Every channel is off until you set its enabled to true. Put secrets in .env and point to them with ${VARIABLE} references.
Telegram
Set up with agentx connect telegram (connect Telegram). One bot per account; each account is bound to one agent.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.telegram.enabled | boolean | false | Turns the Telegram channel on. |
channels.telegram.accounts | map of accounts | {} | One entry per bot, keyed by an account name you choose. |
token | string | required | The bot token from BotFather. Use a ${…} reference. |
agentBinding | string | required | The agent that answers this bot's messages. |
allowFrom | list of strings | — | Who may message this bot: user ids, chat ids (negative numbers), @username, or "*" for everyone (a public bot). Replaces channels.telegram.policy.allowFrom for this account. |
pollInbound | boolean | true | When false, the bot only sends (notifications, replies) and does not read new messages. Use it when the bound agent lives on another machine, so two daemons don't read the same bot. |
channels.telegram.policy.dm | "pair" | "block" | "pair" | Direct-message policy. Written by setup; who may write is decided by allowFrom. |
channels.telegram.policy.group | "mention-required" | "all" | "mention-required" | In groups, mention-required answers only messages that @-mention an agent. |
channels.telegram.policy.allowFrom | list of strings | — | Allowlist used by every account without its own allowFrom. Same entries, including "*". If neither is set, all messages are ignored. |
"telegram": {
"enabled": true,
"accounts": {
"helper": { "token": "${TELEGRAM_BOT_TOKEN}", "agentBinding": "helper", "allowFrom": ["@REPLACE-WITH-YOUR-USERNAME"] }
}
}WhatsApp
Set up with agentx connect whatsapp, which pairs a phone by QR code. Step by step: Answer customers on WhatsApp.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.whatsapp.enabled | boolean | false | Turns the WhatsApp channel on. |
channels.whatsapp.sessionDir | string | ".agentx/whatsapp-sessions" | Folder that keeps the paired session. Delete it to pair again. |
channels.whatsapp.defaultAgent | string | — | Agent that answers when no route matches. |
channels.whatsapp.allowFrom | list of strings | — | Phone numbers (with or without +) or chat IDs the agent may answer (partial match). Unset or empty, no chat is answered (closed by default). With entries, your own self-chat is answered too. "*" answers every chat on the account. See Before you pair WhatsApp. |
channels.whatsapp.routes | list | [] | Send a contact or group to a specific agent. The first match wins. |
contact | string | — | Phone number to match (with or without +). |
group | string | — | Group name or id to match (case-insensitive, partial). |
agent | string | required | Agent that answers matching messages. |
Ingest
Ingest reads contact and group details (and, if you choose, recent messages) into the wiki. Nothing is read unless it is enabled and on an allow list.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.whatsapp.ingest.enabled | boolean | false | Turns ingest on. |
channels.whatsapp.ingest.mode | "metadata-only" | "messages" | "metadata-only" | messages also reads the latest messages of each allowed chat. |
channels.whatsapp.ingest.allowContacts | list of strings | [] | Phone numbers or ids to read (partial match). |
channels.whatsapp.ingest.allowGroups | list of strings | [] | Groups to read. |
channels.whatsapp.ingest.denyContacts | list of strings | [] | Contacts never read, even if allowed. |
channels.whatsapp.ingest.denyGroups | list of strings | [] | Groups never read, even if allowed. |
channels.whatsapp.ingest.messageCap | number (1–500) | 50 | Most messages read per chat in messages mode. |
channels.whatsapp.ingest.historyDays | number (1–365) | 30 | Oldest message age, in days, that is read. |
channels.whatsapp.ingest.contactRefreshDays | number (1–90) | 7 | Days before an unchanged contact is written again. |
channels.whatsapp.ingest.throttle.minMsBetweenCalls | number (≥100) | 1500 | Pause between reads, in milliseconds, so the account isn't flagged. |
channels.whatsapp.ingest.throttle.maxCallsPerMinute | number (≥1) | 20 | Most reads per minute. |
channels.whatsapp.ingest.throttle.maxChatsPerSweep | number (≥1) | 25 | Most chats read in one pass. |
channels.whatsapp.ingest.retentionDays | number (≥0) | 0 | Delete stored raw entries older than this many days. 0 keeps them. |
Email
Set up with agentx connect email, or Settings › Channels › Email. Step by step: Answer customer email. Each mailbox is one account under channels.email.accounts, keyed by an ID such as support.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.email.enabled | boolean | false | Turns the email channel on. |
channels.email.accounts.<id>.agent | string | required | Agent that answers mail sent to this address. |
channels.email.accounts.<id>.address | string | required | The address customers write to. Replies come from it. |
channels.email.accounts.<id>.name | string | the agent's name | Name shown as the sender of replies. |
channels.email.accounts.<id>.imap.host | string | required | IMAP server, for example imap.gmail.com. |
channels.email.accounts.<id>.imap.port | number | 993 | IMAP port. |
channels.email.accounts.<id>.imap.secure | boolean | true | true: TLS from the start (port 993). false: plain, upgraded to TLS when the server offers it (port 143). |
channels.email.accounts.<id>.imap.user | string | the address | Login name, when it is not the address. |
channels.email.accounts.<id>.imap.password | string | — | Use ${EMAIL_<ID>_PASSWORD} and keep the value in .env. For Gmail, an app password. |
channels.email.accounts.<id>.smtp.host | string | required | SMTP server, for example smtp.gmail.com. |
channels.email.accounts.<id>.smtp.port | number | 465 | SMTP port. |
channels.email.accounts.<id>.smtp.secure | boolean | true | true: TLS from the start (port 465). false: upgraded to TLS when the server offers it (port 587). |
channels.email.accounts.<id>.smtp.user | string | the IMAP login | Login name for sending. |
channels.email.accounts.<id>.smtp.password | string | the IMAP password | Password for sending. |
channels.email.accounts.<id>.mailbox | string | "INBOX" | Folder that is read. |
channels.email.accounts.<id>.pollSeconds | number (15–3600) | 60 | How often new mail is fetched. |
channels.email.accounts.<id>.allowFrom | list of strings | — | Who may write: an address, @domain, or "*" for anyone. Unset or empty, every mail is ignored (closed by default). agentx connect email sets ["*"]. |
channels.email.accounts.<id>.send | "approve" | "auto" | "approve" | approve: each reply waits in Approvals (email:<id>) until you send it. auto: replies are sent as soon as the agent writes them. |
Only mail that arrives after the first read is answered. The mailbox is never changed: where AgentX got to is kept in .agentx/email/, with each customer's thread and the waiting replies.
WhatsApp triage
Watched WhatsApp chats, read by an agent that sorts each message and drafts replies for your approval. Messages come from wacli sync --webhook to POST /webhook/wacli, not from the WhatsApp channel above; the two are independent. Set up with Watch a WhatsApp chat, the WhatsApp triage block in Settings › Webhooks, or agentx whatsapp triage.
| Key | Type | Default | What it does |
|---|---|---|---|
whatsappTriage.enabled | boolean | false | Turns triage on. Off, the webhook answers 404. |
whatsappTriage.secretEnv | string | "WACLI_WEBHOOK_SECRET" | Environment variable holding the secret given to wacli sync --webhook-secret. Unset, every message is refused (503). |
whatsappTriage.batchSeconds | number (0–600) | 20 | Messages from one chat within this many seconds go to the agent as one task. |
whatsappTriage.timezone | string | this computer's | Time zone for quiet hours, for example Europe/Paris. |
whatsappTriage.allowAutoAck | boolean | false | Second switch for rules with autoAck. Both must be on. |
whatsappTriage.describeMedia | boolean | true | Download pictures for the agent to look at, and transcribe voice notes when speech to text is set up (voice.stt). |
whatsappTriage.wacli.bin | string | "wacli" | The wacli program, or its full path. |
whatsappTriage.wacli.account | string | — | wacli --account name, when several accounts are paired. |
whatsappTriage.wacli.store | string | — | wacli --store folder. |
whatsappTriage.rules | list | [] | Watch rules. The first enabled match wins. A message no rule matches is dropped and not stored. |
id | string | required | Short name: lowercase letters, digits, - and _. |
enabled | boolean | true | Turns the rule on or off. |
chats | list of strings | [] | Chats to watch: a contact's JID (15550001111@s.whatsapp.net), a group's JID (…@g.us), or a phone number. |
senders | list of strings | [] | Only messages from these people, in any chat the rule covers. A rule needs at least one chat or sender. |
agent | string | required | Agent on this computer that triages the messages. |
prompt | string (≤4000) | — | Extra instructions: who the contact is, where issues go, how to reply. |
quietHours.start, quietHours.end | "HH:MM" | — | No notifications in this window. It may cross midnight. Triage and drafts still happen. |
autoAck | boolean | false | Send the agent's reply to messages it marks ack without asking. Needs allowAutoAck too. |
Every other reply waits in Approvals as a whatsapp: item and is sent only when you say yes.
"whatsappTriage": {
"enabled": true,
"rules": [
{
"id": "test-contact",
"agent": "helper",
"chats": ["+1 555 000 1111"],
"prompt": "Open bug reports in the tracker project example/app.",
"quietHours": { "start": "22:00", "end": "07:00" }
}
]
}GitLab
AgentX receives GitLab webhooks and answers @-mentions in issues and merge requests (watch GitLab).
| Key | Type | Default | What it does |
|---|---|---|---|
channels.gitlab.enabled | boolean | false | Turns the GitLab channel on. |
channels.gitlab.webhookPort | number | 18810 | Separate port that receives GitLab webhooks. |
channels.gitlab.webhookSecret | string | — | Secret GitLab sends in its X-Gitlab-Token header; requests without it are refused. |
channels.gitlab.host | string | "https://gitlab.com" | Address of your GitLab server. |
channels.gitlab.token | string | — | Access token used to post comments. |
channels.gitlab.autoReplyLegacy | boolean | true | When true, the agent's answer is posted as a comment automatically. When false, the agent must post its reply itself. An agent's gitlabAutoReply overrides this. |
channels.gitlab.routes | list | [] | Which agent handles which project. |
project | string | required | Project path, such as group/project, or * for all other projects. |
agent | string | required | Agent for that project. |
channels.gitlab.agentMappings | list | [] | Links GitLab users to agents, so a mention of that user reaches the agent. |
channels.gitlab.ownTokenInAgentEnv | boolean | true | Each agent run gets the agent's own GitLab token in GITLAB_TOKEN, so glab and scripts in its shell write as that agent. See Commands an agent runs. |
agentId | string | required | The agent. |
gitlabUsernames | list of strings | [] | GitLab usernames that stand for this agent. |
keywords | list of strings | [] | Accepted for older configs. Routing uses @-mentions only. |
token | string | — | This agent's own GitLab token, so it comments as itself. |
node | string | — | Mesh node the agent lives on, when it runs on another machine. |
channels.gitlab.noWakeLabel | string | "agent:no-wake" | An issue or merge request carrying this label starts no run and no workflow, on any change or note, even one that @-mentions an agent. A project rule is not needed. Remove the label to let the agent in. "" turns this off. |
"gitlab": {
"enabled": true,
"host": "https://gitlab.example.com",
"token": "${GITLAB_TOKEN}",
"webhookSecret": "${GITLAB_WEBHOOK_SECRET}",
"routes": [{ "project": "*", "agent": "helper" }]
}Which account an agent posts as
An agent's comments, comment edits, label changes, time logs and new issues go out with the first token found here:
- The
tokenin the agent'schannels.gitlab.agentMappingsentry. - Else, if that entry has a
node, the post goes to that mesh computer, which uses its own token for the agent. - Else, a
gitlab-userentry in the agent's ownintegrationslist (see Configuration: agents and runtime). ItstokenEnvnames the variable in.envthat holds the token. - Else, the shared
channels.gitlab.token.
"agents": {
"helper": {
"integrations": [
{ "kind": "gitlab-user", "label": "gitlab-user", "credentials": { "tokenEnv": "HELPER_GITLAB_TOKEN" } }
]
}
}The agent's own GitLab user may not be a member of every project the shared token can reach. When GitLab refuses a write made with an integrations token (error 401, 403 or 404), AgentX tries the same write once more with the shared token. The comment then shows under the shared account, and the daemon log has a line that starts with [gitlab/identity] and names the agent, the project and the error. Other errors are not retried. A token from agentMappings is never retried this way.
Commands an agent runs
Agents also write to GitLab themselves, with glab or a script in their own shell. Those commands read the token in GITLAB_TOKEN. Each agent run now gets the agent's own token there: the one from agentMappings, or else from its integrations entry. Its notes and pushes then show under its own GitLab user, not the shared account.
- An agent with no token of its own keeps the token the daemon was started with.
- The agent's own user must be a member of the projects it works on. If
glabanswers403or404for a project, add that user to the project. - To keep the old behaviour, set
channels.gitlab.ownTokenInAgentEnvtofalseand restart AgentX.
Which issue changes start an agent
An issue change starts an agent only when one of these is true:
- The issue was opened. Agents mentioned in the description start, then agent assignees. If neither exists, the agent in
routesstarts. - An agent was newly assigned.
- A description edit added a mention of an agent. A mention that was already there starts nothing.
A milestone, label, time, estimate, title or state change starts nothing, even on an issue assigned to an agent. The message the agent gets names what changed and who changed it. Comment mentions work as before. An on:gitlab-issue hook decides for itself and is not limited by these rules.
GitHub
| Key | Type | Default | What it does |
|---|---|---|---|
channels.github.enabled | boolean | false | Turns the GitHub channel on. |
channels.github.autoReplyLegacy | boolean | true | Same as the GitLab setting: post the answer automatically, or let the agent post it. |
channels.github.cloudSessions | boolean | false | Lets agents with cloudSessions.enabled send this channel's issue and pull request tasks to Claude cloud sessions. Both must be on. See Send coding tasks to Claude cloud sessions. |
channels.github.token | string | — | Personal access token used to post comments. |
channels.github.tokenFile | string | — | File holding the token (first line is read at start). |
channels.github.appId | number | — | GitHub App id, when you use a GitHub App instead of a token. |
channels.github.clientId | string | — | GitHub App client id (preferred over appId). |
channels.github.privateKeyFile | string | — | Path to the GitHub App private key file. |
channels.github.webhookSecret | string | — | Secret used to check the X-Hub-Signature-256 header of each webhook. |
channels.github.routes | list | [] | Which agent handles which repository. |
repo | string | required | owner/repo, or * for all other repositories. |
agent | string | required | Agent for that repository. |
channels.github.agentMappings | list | [] | Links GitHub users to agents. |
agentId | string | required | The agent. |
githubUsernames | list of strings | [] | GitHub usernames that stand for this agent. |
token | string | — | This agent's own token. |
tokenFile | string | — | File holding this agent's token. |
node | string | — | Mesh node the agent lives on. |
channels.github.issueActions | list of strings | ["opened", "reopened", "assigned"] | Issue changes that start a run. Anything else, such as labeled, edited or closed, starts nothing. |
channels.github.pullRequestActions | list of strings | ["opened", "reopened", "ready_for_review"] | Pull request changes that start a run. |
channels.github.ignoreOwnChanges | boolean | true | A label, assignment, close or edit made by an account AgentX posts with starts no run. This covers the GitHub App, the token owners, the githubUsernames above and accounts of other computers on the mesh. Opening or reopening an issue always counts. |
channels.github.debounceSeconds | number (0–3600) | 30 | Several changes to one issue or pull request within this many seconds start one run. The run sees the latest state and lists every change. Each new change restarts the wait. 0 starts a run for every change. |
channels.github.triggerLabel | string | "agentx" | Adding this label to an issue or pull request starts a run, whoever adds it. Other labels follow issueActions and pullRequestActions. |
channels.github.noWakeLabel | string | "agent:no-wake" | An issue or pull request carrying this label starts no run: not when it is opened, not on a label change, not on a comment or review, even one that @-mentions the agent. A project rule is not needed. Adding the label also drops a run still waiting its debounceSeconds. Remove the label to let the agent in. "" turns this off. |
Which comments start a run
A comment, review or review comment starts a run only when it @-mentions the repository's agent. Any of these counts: @ followed by the agent id (@coder-agent), one of the agent's mentions (@coder), or one of its githubUsernames. A comment without a mention starts nothing, even when a cloud session is already open for the issue. Mentioning a handle without the @ does not count. The daemon log names every comment it skips.
Which changes start a run
GitHub sends a separate message for each change to an issue: opened, labeled, assigned, closed. Without limits, one new issue could start the agent three or four times. First, an issue or pull request carrying noWakeLabel starts nothing, whatever the steps below say. AgentX then filters these messages in three steps:
- Project rule. If the repository has a project rule with an
actionslist undergithub.issuesorgithub.pull_request, that list decides which changes count. Its other filters, such as required labels, still apply. - Channel list. Without such a list,
issueActionsorpullRequestActionsdecides. A rule that only sets labels does not letclosedthrough. To run onclosed, add it to a rule'sactionslist or to the channel list. - AgentX's own changes. A label or assignment that AgentX made itself, for example when it files an issue for an agent, starts nothing while
ignoreOwnChangesis on.
Adding triggerLabel skips steps 2 and 3. A project rule's filters still apply.
Changes that pass all three steps wait debounceSeconds before the agent starts, so a burst becomes one run.
"github": {
"enabled": true,
"routes": [{ "repo": "example/app", "agent": "helper" }],
"issueActions": ["opened", "reopened", "assigned"],
"ignoreOwnChanges": true,
"debounceSeconds": 30
}An agent never answers its own comment. On a mesh, each computer tells its peers which GitHub accounts it posts with, so the computer that receives the webhook also knows a comment that another computer posted for an agent. This needs no setting; both computers must run a version that has it.
push
Sends notifications to the AgentX phone app. It only sends; it does not receive messages. One computer hosts the phone app and sends; every other computer sets relayTo and passes its notifications to that one over the mesh.
| Field | Type | Default | What it does |
|---|---|---|---|
channels.push.enabled | boolean | false | Turns phone app notifications on. |
channels.push.subject | string | — | Contact the push services can reach you at: mailto:you@example.com or an https:// address. Required on the computer that hosts the phone app. |
channels.push.keysFile | string | ".agentx/push-keys.json" | Where agentx app push-keys saves the key pair, relative to the folder AgentX runs in (the one that holds agentx.json). |
channels.push.relayTo | string | — | Mesh peer that hosts the phone app. Set it on every other computer; leave it out on the host. A phone paired with a computer that sets it turns notifications on through that computer, and the host sends them. That needs a token of its own for the host in this computer's mesh.peers, with the same token for this computer in the host's: MESH_TOKEN alone is refused. |
channels.push.ttlSeconds | number | 86400 | How long the push service keeps trying a phone that is offline. |
channels.push.keepRecent | number | 50 | How many recent notifications the app's Alerts tab keeps. |
channels.push.allowedHosts | list of strings | ["fcm.googleapis.com", "push.services.mozilla.com", "push.apple.com", "notify.windows.com"] | Push services a phone may turn notifications on with. Each entry also covers its subdomains. The defaults cover Chrome and Android, Firefox, Safari and iPhone, and Edge. AgentX refuses any other address, because it sends to whatever address the phone gives. |
A message's chat ID picks the phones: default sends to every phone that turned notifications on, and a device id from agentx app devices (it starts with tok_) sends to that phone only. On the host, a phone paired with another computer has the id <computer>:tok_…, where <computer> is the name the host gives that computer in mesh.peers.
app
The phone app beyond pairing and notifications: the AgentX Android app and place reminders. How to set them up, step by step: Place reminders.
| Field | Type | Default | What it does |
|---|---|---|---|
app.android.packageName | string | "dev.agentx.phone" | The Android app's package name (its agentxApplicationId when it was built). |
app.android.certFingerprints | list of strings | [] | SHA-256 fingerprints of the keys that signed the Android app, as AB:CD:… (32 pairs). With at least one, this computer answers /.well-known/assetlinks.json and Chrome shows the app without an address bar. Empty: that address answers 404 and Chrome shows a slim address bar. |
app.places.enabled | boolean | true | Turns place reminders on. Off: the phone app and the Places page say so, and phones' reports are refused. |
app.places.file | string | ".agentx/places.json" | Where places and their reminders are kept, relative to the folder that holds agentx.json. |
app.places.defaultRadiusMeters | number | 150 | Size of a new place when none is given, in metres. |
app.places.minRadiusMeters | number | 100 | Smallest place allowed. Android rarely notices smaller circles reliably. |
app.places.maxRadiusMeters | number | 5000 | Largest place allowed. |
app.places.maxPlaces | number (1 to 100) | 50 | Most places you can save. Android lets one app watch at most 100. |
app.places.maxRulesPerPlace | number (1 to 50) | 10 | Most reminders on one place. |
app.places.cooldownMinutes | number (0 to 1440) | 10 | A reminder set to fire every time fires at most once in this many minutes, so a phone at the edge of a place doesn't buzz again and again. |
app.places.maxEventAgeMinutes | number (1 to 1440) | 30 | A crossing the phone could only report later, for lack of signal, is dropped once it is older than this. |
app.places.syncMinutes | number (15 to 1440) | 60 | How often the Android app checks for added or removed places. Android runs background checks at most every 15 minutes. |
app.pins.file | string | ".agentx/app-pins.json" | Where the phone app's pinned pages are kept, relative to the folder that holds agentx.json. See Pinned pages. |
app.pins.max | number (1 to 50) | 12 | Most pages you can pin as buttons in the phone app, counting app.pins.pages. |
app.pins.pages | array of { label, url } (at most app.pins.max) | [] | Buttons for every paired phone, set here instead of in the app. https:// only; read only in the phone app and agentx app. See Pinned pages. |
ntfy
ntfy sends push notifications to your phone. It only sends; it does not receive messages.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.ntfy.enabled | boolean | false | Turns ntfy on. |
channels.ntfy.server | string | "https://ntfy.sh" | ntfy server; change it if you host your own. |
channels.ntfy.topic | string | — | Default topic. Anyone who knows it can read it, so treat it as a secret. |
channels.ntfy.token | string | — | Access token for protected topics. |
channels.ntfy.defaultPriority | number (1–5) | 3 | Priority when a message sets none. |
channels.ntfy.defaultTitle | string | — | Title when a message sets none (otherwise AgentX). |
When AgentX cannot connect to the ntfy server, or the server answers "busy" (429 or 503), it tries again after 1, 3 and 8 seconds. Each failed try is written to the daemon log with its reason, for example ntfy: attempt 1/4 failed (ntfy: fetch failed code=ETIMEDOUT); retrying in 1000 ms. A notification still not delivered is logged as send failed.
- AgentX gives up after about 20 seconds in total, whatever the number of tries. When that limit stops a try, the log says
send time limit of 20000 ms reached. - It does not try again when the server may already have received the notification: for example when the connection breaks halfway, or the server answers with another error. This way your phone never gets the same notification twice.
Linear and Jira (trackers)
A labelled Linear or Jira issue goes to the agent routed for its team or project, and its answer comes back as a comment. The webhooks arrive at POST /webhook/linear and POST /webhook/jira on the daemon. Keys and secrets are read from the environment variables named below. Set up with Hand Linear and Jira issues to an agent.
| Key | Type | Default | What it does |
|---|---|---|---|
trackers.linear.enabled | boolean | false | Turns Linear on. Off, its webhook answers 404. |
trackers.linear.apiKeyEnv | string | "LINEAR_API_KEY" | Variable holding the Linear API key. |
trackers.linear.webhookSecretEnv | string | "LINEAR_WEBHOOK_SECRET" | Variable holding the webhook's signing secret. Unset, every webhook is refused (503). |
trackers.linear.label | string | "agentx" | The label that hands an issue to an agent. |
trackers.linear.routes | list | [] | { "team", "agent", "checkout"? } per Linear team key. |
trackers.jira.enabled | boolean | false | Turns Jira on. Needs baseUrl. |
trackers.jira.baseUrl | string | — | Your Jira's address, such as https://example.atlassian.net. |
trackers.jira.emailEnv | string | "JIRA_EMAIL" | Variable holding the Jira Cloud account email. Empty for Jira Server, whose token is sent on its own. |
trackers.jira.tokenEnv | string | "JIRA_API_TOKEN" | Variable holding the API token or personal access token. |
trackers.jira.webhookSecretEnv | string | "JIRA_WEBHOOK_SECRET" | Variable holding the webhook's secret. Unset, every webhook is refused (503). |
trackers.jira.label | string | "agentx" | The label that hands an issue to an agent. |
trackers.jira.routes | list | [] | { "project", "agent", "checkout"? } per Jira project key. |
Browser calls (WebRTC)
WebRTC lets people call an agent from a browser.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.webrtc.enabled | boolean | false | Turns calls on. |
channels.webrtc.stunServers | list of strings | ["stun:stun.l.google.com:19302"] | Servers that help two devices find each other across networks. |
channels.webrtc.turnServers | list | [] | Relay servers, needed when both sides are behind strict firewalls. |
urls | string | required | Relay address. |
username | string | — | Relay user name. |
credential | string | — | Relay password. |
channels.webrtc.allowedCallers | list of strings | [] | Mesh peers allowed to start a call. Empty allows all peers. |
channels.webrtc.ringNotify | list | [] | Where to send "someone is calling" messages. Empty sends none. |
channel | string | required | Channel to notify, such as telegram. |
chatId | string | required | Chat to notify. |
accountId | string | — | Which account of that channel sends it. |
channels.webrtc.callUrlBase | string | — | Address used in the join link. Defaults to http:// plus node.bind; set it when people reach the daemon by another name. |
channels.webrtc.camera.width | number (160–3840) | 1280 | Picture width the phone app asks for when it shares its camera. The phone uses the nearest size its camera supports. |
channels.webrtc.camera.height | number (120–2160) | 720 | Picture height the phone asks for. |
channels.webrtc.camera.frameRate | number (1–60) | 15 | Frames per second the phone asks for. |
channels.webrtc.camera.maxSeconds | number (10–7200) | 600 | The phone stops sharing its camera after this many seconds. |
channels.webrtc.camera.voiceInput | boolean | true | Ask a watching agent by voice with Talk. The microphone is on only while you talk and is never part of the share. false shows only the text box. |
channels.webrtc.camera.speakAnswers | boolean | true | Read a watching agent's answers aloud on the phone, in the agent's ElevenLabs voice or the phone's own. Each phone can turn it off with Answers aloud. |
channels.webrtc.camera.bot.frameIntervalSeconds | number (0–3600) | 0 | When an agent watches the camera, how often it gets a picture by itself, in seconds. 0 means only when you tap Look now or the agent asks for one. Each picture the agent gets by itself is a turn of the agent, so keep this high or at 0. |
channels.webrtc.camera.bot.maxSessionMinutes | number (1–240) | 10 | An agent's watch ends after this many minutes, whatever the phone does. |
channels.webrtc.camera.bot.maxFrameEdge | number (160–3840) | 1024 | Pictures are shrunk so their longer side is at most this many pixels before the agent sees them. |
channels.webrtc.camera.bot.keepFrames | boolean | false | Keep the picture files in the agent's workspace (.agentx/camera/) after the share ends. Off: every picture is deleted when the share ends. |
channels.webrtc.camera.bot.streamFrameSeconds | number (2–60) | 5 | While Keep watching is on, the agent gets a picture this often, in seconds. Each picture is a turn of the agent. |
channels.webrtc.camera.bot.streamMaxSeconds | number (10–600) | 60 | Keep watching stops by itself after this many seconds. With 5-second pictures, 60 seconds is about 12 turns and 600 seconds about 120. |
Call bot
The call bot joins a call, writes down what is said and posts it to a chat. It does not speak.
| Key | Type | Default | What it does |
|---|---|---|---|
channels.webrtc.bot.enabled | boolean | false | Turns the call bot on. |
channels.webrtc.bot.defaultAgentId | string | — | Agent the transcript is credited to. |
channels.webrtc.bot.whisperBackend | "auto" | "mlx" | "openai" | "auto" | Speech-to-text engine. auto tries local MLX Whisper, then OpenAI. |
channels.webrtc.bot.whisperModel | string | — | Speech-to-text model name. |
channels.webrtc.bot.whisperLanguage | string | "auto" | Spoken language, or auto to detect it. |
channels.webrtc.bot.mlxBinary | string | — | Full path to mlx_whisper if the daemon can't find it. |
channels.webrtc.bot.transcriptChannel.channel | string | required | Channel that receives the transcript. |
channels.webrtc.bot.transcriptChannel.chatId | string | required | Chat that receives the transcript. |
channels.webrtc.bot.transcriptChannel.accountId | string | — | Which account of that channel sends it. |
channels.webrtc.bot.maxCallMinutes | number (1–240) | 30 | The bot leaves after this many minutes. |
Check it worked
- Terminal: in the folder with
agentx.json, runagentx config check. It prints✓ Config valid. - Terminal: run
agentx config get channels.telegram.enabled(or the field you changed). It prints the new value. - Terminal: restart the daemon, then send the agent a test message on that channel. It answers.
- GitLab: ask an agent that has its own GitLab token to comment on an issue with
glab. The comment shows under that agent's GitLab user.
If something is wrong
config checknames a field: fix that field. Arequiredfield in the tables above is missing.- Telegram ignores every message: neither the account's
allowFromnorchannels.telegram.policy.allowFromis set, or your id isn't in it. - Telegram logs
409 Conflict: two daemons read the same bot. SetpollInboundtofalseon the machine that shouldn't read it. - A GitHub issue starts no run: the daemon log says why, with a line such as
skipped: action="labeled" not in channels.github.issueActions. Add the change toissueActionsor to the project rule'sactionslist. - A GitHub issue still starts several runs: the changes came further apart than
debounceSeconds. Raise it. - An agent's GitLab comment shows under the shared account: run
agentx daemon logsand look for[gitlab/identity].GLOBAL tokenwithagent has no per-agent tokenmeans the agent has no token inagentMappingsor in itsintegrations; add one.refused the agent's integrations tokenmeans its GitLab user can't write to that project; add the user to the project, or fix the token named bytokenEnv. glabin an agent's run answers403or404: the run now uses the agent's own GitLab user, which is not a member of that project. Add the user to the project, or setchannels.gitlab.ownTokenInAgentEnvtofalse.- GitLab says the webhook failed: check that
channels.gitlab.webhookPortis reachable from GitLab and that the secret matcheschannels.gitlab.webhookSecret. - A notification never arrives: run
agentx daemon logsand look forntfy: attemptorsend failedlines.ETIMEDOUTpoints at a slow link (seenode.connectAttemptTimeoutMsin Configuration: agents and runtime); a401or403points at a wrongtokenortopic. - A value is empty at runtime: a
${…}reference points at a variable missing from.env. Add it and restart the daemon.
