Skip to content

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.

KeyTypeDefaultWhat it does
channels.telegram.enabledbooleanfalseTurns the Telegram channel on.
channels.telegram.accountsmap of accounts{}One entry per bot, keyed by an account name you choose.
tokenstringrequiredThe bot token from BotFather. Use a ${…} reference.
agentBindingstringrequiredThe agent that answers this bot's messages.
allowFromlist 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.
pollInboundbooleantrueWhen 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.allowFromlist of strings—Allowlist used by every account without its own allowFrom. Same entries, including "*". If neither is set, all messages are ignored.
json
"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.

KeyTypeDefaultWhat it does
channels.whatsapp.enabledbooleanfalseTurns the WhatsApp channel on.
channels.whatsapp.sessionDirstring".agentx/whatsapp-sessions"Folder that keeps the paired session. Delete it to pair again.
channels.whatsapp.defaultAgentstring—Agent that answers when no route matches.
channels.whatsapp.allowFromlist 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.routeslist[]Send a contact or group to a specific agent. The first match wins.
contactstring—Phone number to match (with or without +).
groupstring—Group name or id to match (case-insensitive, partial).
agentstringrequiredAgent 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.

KeyTypeDefaultWhat it does
channels.whatsapp.ingest.enabledbooleanfalseTurns ingest on.
channels.whatsapp.ingest.mode"metadata-only" | "messages""metadata-only"messages also reads the latest messages of each allowed chat.
channels.whatsapp.ingest.allowContactslist of strings[]Phone numbers or ids to read (partial match).
channels.whatsapp.ingest.allowGroupslist of strings[]Groups to read.
channels.whatsapp.ingest.denyContactslist of strings[]Contacts never read, even if allowed.
channels.whatsapp.ingest.denyGroupslist of strings[]Groups never read, even if allowed.
channels.whatsapp.ingest.messageCapnumber (1–500)50Most messages read per chat in messages mode.
channels.whatsapp.ingest.historyDaysnumber (1–365)30Oldest message age, in days, that is read.
channels.whatsapp.ingest.contactRefreshDaysnumber (1–90)7Days before an unchanged contact is written again.
channels.whatsapp.ingest.throttle.minMsBetweenCallsnumber (≥100)1500Pause between reads, in milliseconds, so the account isn't flagged.
channels.whatsapp.ingest.throttle.maxCallsPerMinutenumber (≥1)20Most reads per minute.
channels.whatsapp.ingest.throttle.maxChatsPerSweepnumber (≥1)25Most chats read in one pass.
channels.whatsapp.ingest.retentionDaysnumber (≥0)0Delete 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.

KeyTypeDefaultWhat it does
channels.email.enabledbooleanfalseTurns the email channel on.
channels.email.accounts.<id>.agentstringrequiredAgent that answers mail sent to this address.
channels.email.accounts.<id>.addressstringrequiredThe address customers write to. Replies come from it.
channels.email.accounts.<id>.namestringthe agent's nameName shown as the sender of replies.
channels.email.accounts.<id>.imap.hoststringrequiredIMAP server, for example imap.gmail.com.
channels.email.accounts.<id>.imap.portnumber993IMAP port.
channels.email.accounts.<id>.imap.securebooleantruetrue: TLS from the start (port 993). false: plain, upgraded to TLS when the server offers it (port 143).
channels.email.accounts.<id>.imap.userstringthe addressLogin name, when it is not the address.
channels.email.accounts.<id>.imap.passwordstring—Use ${EMAIL_<ID>_PASSWORD} and keep the value in .env. For Gmail, an app password.
channels.email.accounts.<id>.smtp.hoststringrequiredSMTP server, for example smtp.gmail.com.
channels.email.accounts.<id>.smtp.portnumber465SMTP port.
channels.email.accounts.<id>.smtp.securebooleantruetrue: TLS from the start (port 465). false: upgraded to TLS when the server offers it (port 587).
channels.email.accounts.<id>.smtp.userstringthe IMAP loginLogin name for sending.
channels.email.accounts.<id>.smtp.passwordstringthe IMAP passwordPassword for sending.
channels.email.accounts.<id>.mailboxstring"INBOX"Folder that is read.
channels.email.accounts.<id>.pollSecondsnumber (15–3600)60How often new mail is fetched.
channels.email.accounts.<id>.allowFromlist 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.

KeyTypeDefaultWhat it does
whatsappTriage.enabledbooleanfalseTurns triage on. Off, the webhook answers 404.
whatsappTriage.secretEnvstring"WACLI_WEBHOOK_SECRET"Environment variable holding the secret given to wacli sync --webhook-secret. Unset, every message is refused (503).
whatsappTriage.batchSecondsnumber (0–600)20Messages from one chat within this many seconds go to the agent as one task.
whatsappTriage.timezonestringthis computer'sTime zone for quiet hours, for example Europe/Paris.
whatsappTriage.allowAutoAckbooleanfalseSecond switch for rules with autoAck. Both must be on.
whatsappTriage.describeMediabooleantrueDownload pictures for the agent to look at, and transcribe voice notes when speech to text is set up (voice.stt).
whatsappTriage.wacli.binstring"wacli"The wacli program, or its full path.
whatsappTriage.wacli.accountstring—wacli --account name, when several accounts are paired.
whatsappTriage.wacli.storestring—wacli --store folder.
whatsappTriage.ruleslist[]Watch rules. The first enabled match wins. A message no rule matches is dropped and not stored.
idstringrequiredShort name: lowercase letters, digits, - and _.
enabledbooleantrueTurns the rule on or off.
chatslist of strings[]Chats to watch: a contact's JID (15550001111@s.whatsapp.net), a group's JID (…@g.us), or a phone number.
senderslist of strings[]Only messages from these people, in any chat the rule covers. A rule needs at least one chat or sender.
agentstringrequiredAgent on this computer that triages the messages.
promptstring (≤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.
autoAckbooleanfalseSend 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.

json
"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).

KeyTypeDefaultWhat it does
channels.gitlab.enabledbooleanfalseTurns the GitLab channel on.
channels.gitlab.webhookPortnumber18810Separate port that receives GitLab webhooks.
channels.gitlab.webhookSecretstring—Secret GitLab sends in its X-Gitlab-Token header; requests without it are refused.
channels.gitlab.hoststring"https://gitlab.com"Address of your GitLab server.
channels.gitlab.tokenstring—Access token used to post comments.
channels.gitlab.autoReplyLegacybooleantrueWhen 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.routeslist[]Which agent handles which project.
projectstringrequiredProject path, such as group/project, or * for all other projects.
agentstringrequiredAgent for that project.
channels.gitlab.agentMappingslist[]Links GitLab users to agents, so a mention of that user reaches the agent.
channels.gitlab.ownTokenInAgentEnvbooleantrueEach 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.
agentIdstringrequiredThe agent.
gitlabUsernameslist of strings[]GitLab usernames that stand for this agent.
keywordslist of strings[]Accepted for older configs. Routing uses @-mentions only.
tokenstring—This agent's own GitLab token, so it comments as itself.
nodestring—Mesh node the agent lives on, when it runs on another machine.
channels.gitlab.noWakeLabelstring"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.
json
"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:

  1. The token in the agent's channels.gitlab.agentMappings entry.
  2. Else, if that entry has a node, the post goes to that mesh computer, which uses its own token for the agent.
  3. Else, a gitlab-user entry in the agent's own integrations list (see Configuration: agents and runtime). Its tokenEnv names the variable in .env that holds the token.
  4. Else, the shared channels.gitlab.token.
json
"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 glab answers 403 or 404 for a project, add that user to the project.
  • To keep the old behaviour, set channels.gitlab.ownTokenInAgentEnv to false and 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 routes starts.
  • 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 ​

KeyTypeDefaultWhat it does
channels.github.enabledbooleanfalseTurns the GitHub channel on.
channels.github.autoReplyLegacybooleantrueSame as the GitLab setting: post the answer automatically, or let the agent post it.
channels.github.cloudSessionsbooleanfalseLets 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.tokenstring—Personal access token used to post comments.
channels.github.tokenFilestring—File holding the token (first line is read at start).
channels.github.appIdnumber—GitHub App id, when you use a GitHub App instead of a token.
channels.github.clientIdstring—GitHub App client id (preferred over appId).
channels.github.privateKeyFilestring—Path to the GitHub App private key file.
channels.github.webhookSecretstring—Secret used to check the X-Hub-Signature-256 header of each webhook.
channels.github.routeslist[]Which agent handles which repository.
repostringrequiredowner/repo, or * for all other repositories.
agentstringrequiredAgent for that repository.
channels.github.agentMappingslist[]Links GitHub users to agents.
agentIdstringrequiredThe agent.
githubUsernameslist of strings[]GitHub usernames that stand for this agent.
tokenstring—This agent's own token.
tokenFilestring—File holding this agent's token.
nodestring—Mesh node the agent lives on.
channels.github.issueActionslist of strings["opened", "reopened", "assigned"]Issue changes that start a run. Anything else, such as labeled, edited or closed, starts nothing.
channels.github.pullRequestActionslist of strings["opened", "reopened", "ready_for_review"]Pull request changes that start a run.
channels.github.ignoreOwnChangesbooleantrueA 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.debounceSecondsnumber (0–3600)30Several 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.triggerLabelstring"agentx"Adding this label to an issue or pull request starts a run, whoever adds it. Other labels follow issueActions and pullRequestActions.
channels.github.noWakeLabelstring"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:

  1. Project rule. If the repository has a project rule with an actions list under github.issues or github.pull_request, that list decides which changes count. Its other filters, such as required labels, still apply.
  2. Channel list. Without such a list, issueActions or pullRequestActions decides. A rule that only sets labels does not let closed through. To run on closed, add it to a rule's actions list or to the channel list.
  3. 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 ignoreOwnChanges is 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.

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

FieldTypeDefaultWhat it does
channels.push.enabledbooleanfalseTurns phone app notifications on.
channels.push.subjectstring—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.keysFilestring".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.relayTostring—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.ttlSecondsnumber86400How long the push service keeps trying a phone that is offline.
channels.push.keepRecentnumber50How many recent notifications the app's Alerts tab keeps.
channels.push.allowedHostslist 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.

FieldTypeDefaultWhat it does
app.android.packageNamestring"dev.agentx.phone"The Android app's package name (its agentxApplicationId when it was built).
app.android.certFingerprintslist 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.enabledbooleantrueTurns place reminders on. Off: the phone app and the Places page say so, and phones' reports are refused.
app.places.filestring".agentx/places.json"Where places and their reminders are kept, relative to the folder that holds agentx.json.
app.places.defaultRadiusMetersnumber150Size of a new place when none is given, in metres.
app.places.minRadiusMetersnumber100Smallest place allowed. Android rarely notices smaller circles reliably.
app.places.maxRadiusMetersnumber5000Largest place allowed.
app.places.maxPlacesnumber (1 to 100)50Most places you can save. Android lets one app watch at most 100.
app.places.maxRulesPerPlacenumber (1 to 50)10Most reminders on one place.
app.places.cooldownMinutesnumber (0 to 1440)10A 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.maxEventAgeMinutesnumber (1 to 1440)30A crossing the phone could only report later, for lack of signal, is dropped once it is older than this.
app.places.syncMinutesnumber (15 to 1440)60How often the Android app checks for added or removed places. Android runs background checks at most every 15 minutes.
app.pins.filestring".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.maxnumber (1 to 50)12Most pages you can pin as buttons in the phone app, counting app.pins.pages.
app.pins.pagesarray 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.

KeyTypeDefaultWhat it does
channels.ntfy.enabledbooleanfalseTurns ntfy on.
channels.ntfy.serverstring"https://ntfy.sh"ntfy server; change it if you host your own.
channels.ntfy.topicstring—Default topic. Anyone who knows it can read it, so treat it as a secret.
channels.ntfy.tokenstring—Access token for protected topics.
channels.ntfy.defaultPrioritynumber (1–5)3Priority when a message sets none.
channels.ntfy.defaultTitlestring—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.

KeyTypeDefaultWhat it does
trackers.linear.enabledbooleanfalseTurns Linear on. Off, its webhook answers 404.
trackers.linear.apiKeyEnvstring"LINEAR_API_KEY"Variable holding the Linear API key.
trackers.linear.webhookSecretEnvstring"LINEAR_WEBHOOK_SECRET"Variable holding the webhook's signing secret. Unset, every webhook is refused (503).
trackers.linear.labelstring"agentx"The label that hands an issue to an agent.
trackers.linear.routeslist[]{ "team", "agent", "checkout"? } per Linear team key.
trackers.jira.enabledbooleanfalseTurns Jira on. Needs baseUrl.
trackers.jira.baseUrlstring—Your Jira's address, such as https://example.atlassian.net.
trackers.jira.emailEnvstring"JIRA_EMAIL"Variable holding the Jira Cloud account email. Empty for Jira Server, whose token is sent on its own.
trackers.jira.tokenEnvstring"JIRA_API_TOKEN"Variable holding the API token or personal access token.
trackers.jira.webhookSecretEnvstring"JIRA_WEBHOOK_SECRET"Variable holding the webhook's secret. Unset, every webhook is refused (503).
trackers.jira.labelstring"agentx"The label that hands an issue to an agent.
trackers.jira.routeslist[]{ "project", "agent", "checkout"? } per Jira project key.

Browser calls (WebRTC) ​

WebRTC lets people call an agent from a browser.

KeyTypeDefaultWhat it does
channels.webrtc.enabledbooleanfalseTurns calls on.
channels.webrtc.stunServerslist of strings["stun:stun.l.google.com:19302"]Servers that help two devices find each other across networks.
channels.webrtc.turnServerslist[]Relay servers, needed when both sides are behind strict firewalls.
urlsstringrequiredRelay address.
usernamestring—Relay user name.
credentialstring—Relay password.
channels.webrtc.allowedCallerslist of strings[]Mesh peers allowed to start a call. Empty allows all peers.
channels.webrtc.ringNotifylist[]Where to send "someone is calling" messages. Empty sends none.
channelstringrequiredChannel to notify, such as telegram.
chatIdstringrequiredChat to notify.
accountIdstring—Which account of that channel sends it.
channels.webrtc.callUrlBasestring—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.widthnumber (160–3840)1280Picture width the phone app asks for when it shares its camera. The phone uses the nearest size its camera supports.
channels.webrtc.camera.heightnumber (120–2160)720Picture height the phone asks for.
channels.webrtc.camera.frameRatenumber (1–60)15Frames per second the phone asks for.
channels.webrtc.camera.maxSecondsnumber (10–7200)600The phone stops sharing its camera after this many seconds.
channels.webrtc.camera.voiceInputbooleantrueAsk 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.speakAnswersbooleantrueRead 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.frameIntervalSecondsnumber (0–3600)0When 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.maxSessionMinutesnumber (1–240)10An agent's watch ends after this many minutes, whatever the phone does.
channels.webrtc.camera.bot.maxFrameEdgenumber (160–3840)1024Pictures are shrunk so their longer side is at most this many pixels before the agent sees them.
channels.webrtc.camera.bot.keepFramesbooleanfalseKeep 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.streamFrameSecondsnumber (2–60)5While 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.streamMaxSecondsnumber (10–600)60Keep 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.

KeyTypeDefaultWhat it does
channels.webrtc.bot.enabledbooleanfalseTurns the call bot on.
channels.webrtc.bot.defaultAgentIdstring—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.whisperModelstring—Speech-to-text model name.
channels.webrtc.bot.whisperLanguagestring"auto"Spoken language, or auto to detect it.
channels.webrtc.bot.mlxBinarystring—Full path to mlx_whisper if the daemon can't find it.
channels.webrtc.bot.transcriptChannel.channelstringrequiredChannel that receives the transcript.
channels.webrtc.bot.transcriptChannel.chatIdstringrequiredChat that receives the transcript.
channels.webrtc.bot.transcriptChannel.accountIdstring—Which account of that channel sends it.
channels.webrtc.bot.maxCallMinutesnumber (1–240)30The bot leaves after this many minutes.

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 channels.telegram.enabled (or the field you changed). It prints the new value.
  3. Terminal: restart the daemon, then send the agent a test message on that channel. It answers.
  4. 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 check names a field: fix that field. A required field in the tables above is missing.
  • Telegram ignores every message: neither the account's allowFrom nor channels.telegram.policy.allowFrom is set, or your id isn't in it.
  • Telegram logs 409 Conflict: two daemons read the same bot. Set pollInbound to false on 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 to issueActions or to the project rule's actions list.
  • 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 logs and look for [gitlab/identity]. GLOBAL token with agent has no per-agent token means the agent has no token in agentMappings or in its integrations; add one. refused the agent's integrations token means its GitLab user can't write to that project; add the user to the project, or fix the token named by tokenEnv.
  • glab in an agent's run answers 403 or 404: 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 set channels.gitlab.ownTokenInAgentEnv to false.
  • GitLab says the webhook failed: check that channels.gitlab.webhookPort is reachable from GitLab and that the secret matches channels.gitlab.webhookSecret.
  • A notification never arrives: run agentx daemon logs and look for ntfy: attempt or send failed lines. ETIMEDOUT points at a slow link (see node.connectAttemptTimeoutMs in Configuration: agents and runtime); a 401 or 403 points at a wrong token or topic.
  • A value is empty at runtime: a ${…} reference points at a variable missing from .env. Add it and restart the daemon.

Released under the MIT License.