Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
Channel real-service verification
This runbook is the live verification matrix for bot channels. It checks each messaging provider against a real service account, not a fake transport. Runtime tests already cover the code paths; this matrix proves credentials, delivery, restore, and repair against the vendor.
Run it whenever the channel runtime, a transport, or the health contract changes, and before marking a provider's channel work complete in a milestone.
Isolation rules
- Always run against an isolated Akeru home. Never point the test server at
~/.akeru/userdataor~/.akeru/dev, and never symlink. - Use a dedicated test home, for example
AKERU_HOME=$(mktemp -d /tmp/akeru-channels.XXXXXX). To reuse real bots and projects, snapshot the database withVACUUM INTOas described in the project AGENTS.md test data section, and leave secrets behind. Enter fresh channel credentials in the test home. - Use a throwaway workspace and test messaging accounts. Do not verify against workspaces, servers, phone numbers, or Slack workspaces that carry real conversations.
- A standard-scope pairing token is enough to watch chats. Managing connections under Settings > Bot channels needs an administrator session, so keep the startup pairing URL.
- Stop the test server by the PID you started, and remove the temporary home afterward.
- Evidence (screenshots, message logs, timings) goes to the tracking issue, not the repository.
Shared checklist
Run every step for each provider unless that provider's section marks a step not applicable.
- Connect. Save credentials, assign a bot and a project, and connect. The binding reaches
connectedand the card reports no error. - Inbound message. Send a message that the provider's conversation policy accepts (see the per-provider table). A new Akeru thread appears under the selected project, labeled with the channel origin.
- Reply. The connected bot's final reply posts back to the same external conversation once the turn completes. No intermediate tool output reaches the channel.
- Delivery states. Watch the reply in the Akeru conversation. It moves from sending to sent. To see
failed, revoke or break the credential mid-test and retry the reply. To seeunknown, cut the network between the send and the provider response; the attempt must not repost on its own, and the channel card must show the delivery warning with a Check the channel action. - Thread continuation (Slack and Discord). Reply inside the same platform thread without a new mention. The message continues the same Akeru thread.
- Repair. For each health state, confirm the card offers exactly one repair action: reconnect after a dropped connection, update credentials after a rejected token, choose another project after the project is removed, set a public URL for WhatsApp
not-live. - Disconnect and reconnect. Disconnect stops inbound delivery and clears status reactions. Reconnect resumes inbound delivery without duplicating earlier replies.
- Restore after restart. Stop the server, start it again on the same home, and send another inbound message. The channel restores without a manual reconnect. Then break a credential, restart again, and confirm the binding comes back
failedwith therestorecategory and the server still starts. - Authorization refusal. Connect a standard-scope client and attempt each
channel.*command. Every one is refused. The card must not offer repair actions the session cannot perform. - Reply footer. With a public origin configured, an external reply ends with the Open in Akeru link. Without one, no link appears.
- Status reactions (Slack and Discord). The request message gains an eyes reaction on accept, an hourglass while the turn waits on an approval or answer, a check on completion, and an X on failure or cancellation.
- Bot-authored messages. Messages sent by the Akeru bot itself, and by any other connected bot, never start work.
Provider requirements and status
Telegram
Needs: a BotFather bot token (/newbot). Free and the cheapest provider to verify, so run it first.
Policy notes: direct messages only. A group message must not start work. Telegram messages sent on behalf of a chat report an unknown author and are ignored only when they are explicitly marked as bot-authored.
Matrix result, 2026-09-26: unverified: no credentials.
Slack
Needs: a Slack app on a test workspace.
- Socket Mode enabled.
- One app-level token with the
connections:writescope. Akeru probes it withapps.connections.openbefore connecting; an auth failure reports invalid token, a network failure reports Slack unreachable. - A bot token installed to the workspace.
- Bot event subscriptions:
message.imfor direct messages,app_mentionfor channel mentions, andmessage.channelsso replies inside subscribed platform threads continue the Akeru thread. - Bot scopes covering
chat:write,reactions:write,im:history,im:read,im:write,channels:history,channels:read, andapp_mentions:read.
Verify that a mention reply lands inside the Slack thread (thread_ts), not at the channel root. Socket Mode is outbound only, so no public URL is required.
Matrix result, 2026-09-26: unverified: no credentials.
Discord
Needs: a Discord application and bot on a test server.
- Privileged gateway intents: enable Message Content Intent in the developer portal. The adapter requests Guilds, Guild Messages, Message Content, Direct Messages, Guild Message Reactions, and Direct Message Reactions.
- Copy the application ID, public key, and bot token into the connection form. The public key is required even though Akeru only uses the gateway.
- Invite the bot with the generated link. Its permission set covers viewing channels, sending messages, reading message history, creating and using threads, and adding reactions.
Verify that a first server mention creates a Discord thread on that message, that role mentions and @everyone do not start work, and that the supervised gateway renews across its hourly listener boundary.
Matrix result, 2026-09-26: unverified: no credentials.
iMessage (Photon)
Needs: a Photon account, either hosted credentials (project ID and project secret) or a self-hosted Photon server on macOS (server URL, API key, optional phone). The hosted option can use a shared project number.
Policy notes: direct messages only, no group chats. All post errors stay ambiguous because Photon's internal retries cannot be classified; treat any failed send as unknown until the conversation confirms otherwise. The gateway listener renews hourly; keep a session running past the boundary at least once.
Matrix result, 2026-09-26: unverified: no credentials.
Needs: a Meta Business app with the WhatsApp Business Cloud API, a phone number ID, an access token, an app secret, a verify token, and a public HTTPS origin for the environment server (--public-origin or T3CODE_PUBLIC_ORIGIN).
- Without a public origin the binding must save as
not-liveand no webhook URL appears in the profile. - With a public origin the server writes the webhook URL (
/api/channels/whatsapp/connections/<connection-id>/webhook) into the connection profile. Configure that URL and the verify token in the Meta app dashboard. The older per-bot route (/api/channels/whatsapp/<bot-id>/webhook) still accepts calls. - Verify Meta's GET challenge and a signed POST. An altered signature must be rejected.
- WhatsApp can accept an earlier text chunk before failing, so treat post failures as ambiguous delivery, never a confirmed rejection.
Matrix result, 2026-09-26: unverified: no credentials.
Recording results
Update the matrix line for each provider with the date, the result, and a link to the evidence on the tracking issue. A provider without credentials stays unverified; do not mark it complete. Any defect found during the run goes back to the lane that owns the code, not into a docs commit.