| Docs

Deep reference and practical runbook

Use Dexbot With Confidence

This documentation explains exactly how Dexbot works, how to configure it, and how to run it safely in daily operations. It follows a practical, operator-first format so users can get started quickly and still go deep.

Open GitHub Repo Back To Homepage

Who Are You? Where To Start?

You Are...	Start Here
New to Dexbot	Read Quick Start, then run `npm run onboard`.
Already installed, want daily usage	Go to Command Reference and Schedules.
Need repeatable workflows	Use Skills Guide and /skill commands.
Deploying docs/pages	Use Cloudflare Pages Deploy section.
Running in groups/topics	Review Security and Operations Runbook first.

Documentation Map

Getting Started

Install, onboard, verify bot identity, run first commands.

Core Runtime

Memory model, topic scopes, Codex execution flow, skills, schedules.

Production Ops

Security, access controls, restart strategy, autostart, troubleshooting.

Quick Start

git clone https://github.com/alanayoubi/Dexbot.git
cd Dexbot
npm install
npm run onboard
npm run start

After startup, validate identity and scope with /whoami and /chatid.

Setup And Configuration

Required Inputs

TELEGRAM_BOT_TOKEN
ALLOWED_TELEGRAM_USER_IDS
Optional: ALLOWED_TELEGRAM_CHAT_IDS
Access profile: full, partial, read-only, or custom

Recommended Safety Defaults

TELEGRAM_PRIVATE_ONLY=true
TELEGRAM_GROUP_REQUIRE_MENTION=true
chmod 600 .env
Run on isolated machine if using full access

Dexbot supports a local dashboard and Telegram usage. You can run both in parallel.

Core Concepts

Gateway Pattern

Dexbot acts as the Telegram gateway to Codex runtime, handling message ingestion, context preparation, and response delivery.

Session Scoping

Each chat/topic can run isolated memory and scheduling scope to avoid cross-project contamination.

Memory Layers

Working memory per turn, session memory per scope, and canonical long-term memory files with index/retrieval support.

Tooling

Dexbot can execute shell commands and file operations through Codex capabilities, governed by your runtime configuration.

Telegram Command Reference

/startOverview and available capabilities.

/newsessionReset thread and start new session memory.

/memoryView scope memory status and artifacts.

/heartbeatRun maintenance pass manually.

/scheduleCreate/list/pause/resume/run proactive jobs.

/skillManage skill lifecycle and execution.

/restartRestart bot and app-server safely.

/autostartControl Mac reboot startup behavior.

/chatidOutput chat id and topic id.

/whoamiOutput Telegram user id and sender context.

Skills Guide

/skill list
/skill paths
/skill show sales-pages
/skill create  |  | 
/skill run  | 
/skill delete

Direct inline trigger also works: $sales-pages <task>.

Skill format: <skills-root>/<skill-name>/SKILL.md
Use skills for repeatable workflows with context-specific logic.
When intent is unclear for skill creation, ask follow-up before creating.

Schedules And Automation

/schedule add daily 09:00 | Send my morning report with priorities and blockers.
/schedule add heartbeat 13:30 | Check in and ask what to focus on now.
/schedule list
/schedule run 3
/schedule pause 3
/schedule resume 3
/schedule remove 3

Schedules are topic-aware and scope-isolated.
Timezone defaults to local machine, override per job with tz=Area/City.
Natural language scheduling is supported when intent is clear.

Media And Transcription

Telegram Media

Dexbot handles images, documents, videos, voice notes, and audio files directly from chat.

AssemblyAI Pipeline

Use YouTube/audio pipeline for transcription outputs and reports saved under data/transcripts.

npm run yt:transcribe -- "https://www.youtube.com/watch?v=VIDEO_ID"

Cloudflare Pages Deploy

Required env vars: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.
Recommended token scope: Pages Edit + Account Settings Read (+ DNS Edit/Zone Read only if needed).
Deploy using Wrangler to your Pages project branch.

npx wrangler pages deploy deploy/dexbot --project-name dexbot --branch main

Security

Access Control

Always enforce allowlists for users and optionally chat ids.

Secrets

Keep tokens in .env only, never commit, rotate if exposed.

Isolation

Run high-access modes only on isolated machines.

Operations Runbook

Daily Health Checks

Run /memory for scope sanity.
Run /schedule list to verify active jobs.
Confirm recent command responsiveness.

Recovery Steps

Use /restart first.
Validate env and allowlists.
Re-test with /whoami and /chatid.

FAQ

Is Dexbot free?

Yes. Dexbot is open source. You bring your own Codex login and API/provider usage costs where applicable.

Does Dexbot run locally?

Yes. It runs on your own machine, which gives you direct control of environment, data, and automation.

Can I use it in Telegram groups?

Yes, with proper allowlists and mention requirements. Topic scoping keeps context isolated.

Can I extend it?

Yes. Add skills, schedules, scripts, and deployment workflows based on your operating model.