Chat with Kepler from your phone

Kepler runs on your desk. The Gateway lets you reach it from your phone through WhatsApp, Slack, Telegram, Discord, or any chat a plugin brings, in the same session you were working in. Ask a question on the train, approve a command from the sofa, get woken by a watcher when you have stepped away. Kepler answers as long as it is running on your machine. The reliable choices first: Telegram is the most dependable option and takes three steps. Slack and Discord are official bot integrations and work well. WhatsApp is the most convenient but is not an official integration, so read the warning below before relying on it.

Connect a channel

Open Settings > Gateway and choose Connect a channel. Each channel walks you through its own steps. Tokens go to your operating system keychain, never to a file. One bot account runs in one channel. If you try to connect a second channel with a token that is already in use, Kepler refuses and names the channel using it.

Telegram
Slack
Discord
WhatsApp

Create a bot

Open Telegram and message @BotFather. Send /newbot and give it a name.

Paste the token

BotFather replies with a bot token. Paste it into Kepler as the Bot token.

Add yourself

Under Who can message, add your @username or numeric user ID. Telegram never gives a bot your phone number, so a phone number here will not match.

Message your bot from Telegram. Kepler answers.

Create a Slack app

At api.slack.com/apps, create an app From scratch.

Make an app-level token

Under Settings > Basic Information > App-Level Tokens, generate a token with the connections:write scope. This is the xapp- token.

Turn on Socket Mode

Under Settings > Socket Mode, enable it.

Add bot scopes

Under Features > OAuth & Permissions > Bot Token Scopes, add chat:write, im:history, users:read and files:read. To use Kepler in channels, also add app_mentions:read.

Subscribe to events

Under Features > Event Subscriptions, turn it on and subscribe to the bot event message.im. For channels, also add app_mention.

Allow direct messages

Under Features > App Home > Messages Tab, turn it on and tick Allow users to send Slash commands and messages from the messages tab. Without this Slack refuses direct messages to the app.

Install and paste both tokens

Install the app to your workspace. The Bot User OAuth Token starts with xoxb-. Paste the xapp- and xoxb- tokens into Kepler.

If you add a scope later, reinstall the app to your workspace or the new permission never takes effect.

Under Who can message, add your Slack member ID (starts with U) or @handle.

Settings > Gateway in Kepler with Telegram connected under a Connected heading, marked No senders yet. Below it the per-channel options: What it can do set to Observe, Default workspace, Show typing, and Who can message reading Nobody yet.

Add a channel

Kepler can talk on more than the four built-in chats. A channel for another platform comes as part of a plugin. Press Add channel on the Gateway page and pick one of three ways in:

Option	What it does
Install one	Opens the plugin browser, showing only plugins that bring a channel.
Run a channel server	For a server you already have that speaks Kepler’s channel format. Give its name, command, arguments, and the settings it needs, and mark which are secret. Kepler wraps it in a small plugin for you to review.
Build one with Kepler	Opens `/channels`. Describe the platform. Kepler looks for an existing channel plugin first. If there is none, it writes the channel in your workspace, checks that it works, and proposes it.

Each way ends in the same plugin review, so a channel you make yourself keeps its secrets in the keychain and gets the same row on the Gateway page as a built-in one, tagged with its plugin’s name. Kepler never asks for a token in chat. You enter it when you connect the channel. You can also start from any session:

/channels add a channel for our in-house chat server

/channels on its own lists your channels and what each one is doing. A channel runs on your machine, so it has to reach out to its platform, by polling an API or holding a connection open. A platform that can only push webhooks to a public address needs a tunnel.

Bind a session to your phone

By default a message from your phone starts or continues a chat in the channel’s default workspace. To drive a specific session you already have open, run this in that session:

/otg whatsapp

Kepler binds the session to that channel. Messages from your phone arrive in the session, replies go back to your phone, and the session’s watchers can reach you there too. Swap whatsapp for telegram, slack or discord. Turn it off with:

/otg off

What you can do from the channel

Ask anything you would ask at your desk. The session keeps its context, so “and the logs?” means what it would mean in the app.
Answer approvals. When Kepler is waiting on a command in Assist, the approval reaches the chat the run came from. Reply yes or no, or /approve or /deny, and it counts the same as pressing the button in the app. A plugin channel that has its own approval buttons shows those instead, and Kepler accepts the answer only for a request it asked, on that same channel.
Run an automation. An automation with a chat trigger is a command in every connected chat: /triage checkout is throwing 502s runs it with that text, and its answer comes back in the same chat. Your conversation carries on untouched.
Be woken by a watcher. With Reach me when I’m away on under Settings > General > When you’re away, alerts that need action go to a connected channel once your screen is locked or idle. Routine notifications never do.

Which session a message goes to

Each chat talks to one session. Where the platform has threads, such as a Slack thread under an @mention, each thread gets its own session.

While you keep talking, the session stays warm and Kepler remembers what you were doing.
After six quiet hours, the next message starts a fresh session, so the next morning’s question does not carry yesterday’s incident. Kepler tells you when this happens. /sessions and /switch take you back.
A thread never goes cold. A new thread is a new session, and a reply in it continues that one.
/new always starts fresh.

Kepler never moves a chat to another session on its own. Only a command does, and Kepler names the session when it changes.

Commands in a chat

Send these as a message in any connected chat. They answer at once and never start a model run.

Command	What it does
`/sessions`	List your recent sessions.
`/switch <n>`	Move this chat to session number `n` from the list.
`/new [title]`	Start a fresh session here.
`/status`	What is running right now.
`/model`	Show this session’s model. `/model <n or name>` switches it, `/model default` resets it.
`/info`	Posture, model, context and stats for this session.
`/pending`	What Kepler is waiting on you for.
`/approve [why]`	Let the waiting step run.
`/deny [why]`	Refuse it. Anything after the command is passed on as a note, such as “wrong namespace”.
`/cancel`	Stop the run in this session.
`/otg off`	Stop driving the session pushed from the desktop.
`/help`	This list, plus the automations this chat can run.

Who can reach Kepler

Every message is checked against the channel’s Who can message list before anything else happens. A message from anyone else is dropped with no reply, no read receipt and no typing indicator. A message in a group never adds anyone new to the list. Kepler also tells the model where each message came from and to treat the text as outside input. A message from a chat cannot change the posture, approve anything, or give instructions on your behalf.

When Kepler posts first

In Assist and Yolo, Kepler can send a message to a channel on its own, for example to post a summary to #incidents when you ask it to. A message to your own chat, or to a conversation you already approved, goes out at once. Anything else waits for your OK on a card, Yolo included. If a message cannot be delivered, Kepler tries once more. If it still fails, it lands in the Feed as “Could not deliver”, so it is never lost. A channel whose connection keeps dropping is restarted with a growing wait. After five failures in ten minutes it stops and shows the last error on its row.

Channel options

Each connected channel has its own settings in Settings > Gateway.

Option	What it does
What it can do	The posture for this channel: Observe, Ask before changes, or Act within bounds. Observe is the default, because you are not watching this surface. A channel can never act more freely than the posture you set here.
Default workspace	Where new chats from this channel land.
Reply in channels	Answer @mentions in Slack or Discord channels, not only direct messages.
Show typing	Show a typing indicator while Kepler works.
Read receipts	Mark messages as read when Kepler has seen them.
Who can message	The allowlist. Only these people get an answer. Everyone else is ignored.

Disconnect everything turns off every channel at once. The people you allowed are kept, so reconnecting is quick.

How Kepler signs its replies

Kepler stamps a name and emoji on the replies it sends, so a message from Kepler never reads as one from you. Set them under Signature in Settings > General. On WhatsApp self-chat every reply is signed. On Telegram, Slack and Discord the bot already has its own name, so Sign replies everywhere stays off unless you want it.

Build your own channel

A channel is an MCP server that a plugin names under channels in its .kepler-plugin/plugin.json. The server declares the kepler/channel capability, sends each incoming message as a notifications/kepler/channel notification, and offers a reply tool that takes chat_id and text. It can also relay approvals and show a typing indicator. Kepler never offers a channel’s server to the model as tools.

{
  "mcpServers": {
    "mychat": {
      "command": "node",
      "args": ["${KEPLER_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [{
    "server": "mychat",
    "displayName": "My Chat",
    "userConfig": {
      "bot_token": { "type": "string", "title": "Bot token", "sensitive": true }
    }
  }]
}

The easiest start is /channels with a description of the platform. Kepler writes the server against this format and checks it before proposing it. Channel servers written for Claude Code use the same format under claude/ names, and run in Kepler as they are.

Where to go next

Automations

Run an automation from a chat, and post its answer back.

Watchers

The thing most worth being woken for.

Postures

What Observe, Assist and Yolo mean for a channel.

Troubleshooting

Dropped links and silent bots.

Settings reference

The Gateway section in Settings.

Get started

Using Kepler

Workflows

Reference

Chat with Kepler from your phone

Connect a channel

Add a channel

Bind a session to your phone

What you can do from the channel

Which session a message goes to

Commands in a chat

Who can reach Kepler

When Kepler posts first

Channel options

How Kepler signs its replies

Build your own channel

Where to go next

Automations

Watchers

Postures

Troubleshooting

Settings reference

​Connect a channel

​Add a channel

​Bind a session to your phone

​What you can do from the channel

​Which session a message goes to

​Commands in a chat

​Who can reach Kepler

​When Kepler posts first

​Channel options

​How Kepler signs its replies

​Build your own channel

​Where to go next

Automations

Watchers

Postures

Troubleshooting

Settings reference

Connect a channel

Add a channel

Bind a session to your phone

What you can do from the channel

Which session a message goes to

Commands in a chat

Who can reach Kepler

When Kepler posts first

Channel options

How Kepler signs its replies

Build your own channel

Where to go next