You send a private Telegram message to a bot telekit is polling. If you are allowed, the bridge starts (or resumes) a headless session in the active node with the current harness, then sends the answer back. Formatted Telegram text works too. Telekit converts visible text, including headings, quotes, and nested lists, into readable plain text before the turn starts. Bullets and list indentation stay in the message. Media embedded in formatted text is not included; send a photo, video, audio, or file separately.

​
Allowlist

A private message is accepted only when:
  • it is a 1:1 private chat, and
  • both the chat id and the author id are an allowed user for that bot profile.
A group is accepted only when that group is on its own allow list and every human in it is listed. The group has its own lane. It does not use your private folder, thread, or passcode. See Group chats. Channels, anonymous admins, unknown groups, and everyone else are dropped before any model call. Forwarded or pasted text is still data. It can contain prompt-injection. Treat the Telegram body as data, not as new instructions.

​
A lane

Continuity is keyed by profile + user + node + thread + harness. Switching node, thread, or harness is a different session id. /new clears only the current lane. Switching harness still starts a new session, but /harness carries the recent conversation so the next turn is not cold.

​
What happens to one message

  1. Allowlist check.
  2. If the passcode gate is on and this lane is locked: only locked-safe commands run.
  3. Slash command → handled locally (no model), unless it is unknown, in which case it is a normal turn.
  4. With /ack on, a cheap model may answer trivia or ack instantly. Everything else is a full harness turn.
  5. The harness runs in the active node’s directory (or TELEKIT_WORKING_DIR / a /node ~/path/ folder).
  6. The reply comes back in Telegram. Files in the turn outbox are sent after the text.
If you set up voice transcription, a Telegram voice note or audio file becomes message text before the agent turn. That text stays in the session until /new, the same as a typed message. The full transcript is previewed in chat only when voice echo is on. If transcription fails, the agent receives the audio file and you see a short reason.

​
Progress while it thinks

/stream controls how much you see before the final answer. See Stream and turns.

​
Mid-turn

A second message on the same lane while a turn is running is a steer (Claude always; Telekit harness when it supports it). This includes a turn that was just sent and has not started yet — messages fired seconds apart fold into one turn rather than becoming two. Other lanes are independent. /stop (or /x) cancels your lane’s running turn and any queued turns behind it. A turn that had to wait its turn announces itself when it starts (▶️ Starting your earlier message: …), so an answer never arrives out of nowhere.

​
/restart

Owner only. Runs telekit restart. Do not use it to wipe a passcode lockout from a locked chat — failed guesses hold /restart until you unlock.