https://github.com/michaelasper/telellm
Telegram group chat bridge for sandboxed Codex CLI sessions
https://github.com/michaelasper/telellm
codex docker openai rust telegram
Last synced: about 2 months ago
JSON representation
Telegram group chat bridge for sandboxed Codex CLI sessions
- Host: GitHub
- URL: https://github.com/michaelasper/telellm
- Owner: michaelasper
- License: mit
- Created: 2026-05-01T14:46:58.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-01T16:44:42.000Z (about 2 months ago)
- Last Synced: 2026-05-01T17:21:58.298Z (about 2 months ago)
- Topics: codex, docker, openai, rust, telegram
- Language: Rust
- Size: 230 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# telellm
[](Cargo.toml)
[](Dockerfile.sandbox)
[](docs/how-to/configure-codex-auth.md)
[](LICENSE)
`telellm` connects Telegram groups and DMs to isolated Codex CLI runtimes.
Each chat gets its own Docker workspace, queue, memory context, and Codex session.
It supports two credential modes:
- `chatgpt_oauth` for Codex CLI access backed by a ChatGPT subscription login.
- `broker_api_key` for host-held OpenAI API keys with per-chat broker tokens.
## Quick Start
```bash
cp config.example.toml config.toml
export TELEGRAM_BOT_TOKEN="..."
docker build -f Dockerfile.sandbox -t telellm-sandbox:local .
cargo run -- doctor --config config.toml --create-network
cargo run -- run --config config.toml
```
For ChatGPT subscription auth, log in on the host and point the config at the Codex auth file:
```bash
codex login --device-auth
```
```toml
[codex]
auth_mode = "chatgpt_oauth"
auth_host_path = "/Users/you/.codex/auth.json"
```
For API-key broker mode, keep the default `auth_mode = "broker_api_key"` and export the upstream key in the daemon environment:
```bash
export OPENAI_API_KEY="sk-..."
```
Set `telegram.allowed_chat_ids` before putting the bot in real groups. An empty allow-list accepts every chat that can reach the bot.
## What It Does
- Routes Telegram mentions, replies, slash commands, and DMs into Codex.
- Imports addressed Telegram photos and documents into the chat workspace for Codex.
- Sends files generated by Codex from the chat workspace back to Telegram.
- Shows Telegram typing indicators and streams partial Codex output by editing a bot-owned message.
- Supports configurable Telegram response formatting with plain text, MarkdownV2, or HTML.
- Keeps one persistent Docker workspace volume per Telegram chat.
- Stores durable group memory in SQLite and rolling recent context in memory.
- Lets groups manage their own runtime with `/status`, `/reset`, `/restart`, and `/rebuild`.
- Keeps the Docker socket and host secrets out of normal sandbox mounts.
## Documentation
Start here:
- [First run tutorial](docs/tutorials/first-run.md)
- [Telegram access setup](docs/how-to/configure-telegram-access.md)
- [Codex authentication setup](docs/how-to/configure-codex-auth.md)
- [Generated files](docs/how-to/send-generated-files.md)
- [Runtime troubleshooting](docs/how-to/validate-and-troubleshoot.md)
- [Configuration reference](docs/reference/configuration.md)
- [Runtime and security model](docs/explanation/runtime-and-security.md)
The full documentation map is in [docs/README.md](docs/README.md).
## Development
```bash
./scripts/check.sh
cargo audit
```
`scripts/check.sh` runs `cargo fmt --check`, `cargo test`, and Clippy with warnings denied.
## Security
Read [SECURITY.md](SECURITY.md) before exposing a daemon to shared groups.
The short version:
- Keep `profiles/`, `.env`, and local data out of git and Docker build contexts.
- Use explicit `allowed_chat_ids` outside of temporary setup.
- Treat everyone in an allowed Telegram chat as able to control that chat's sandbox.
- Use `chatgpt_oauth` only for chats trusted with the copied Codex subscription auth inside their sandbox.