> For the complete documentation index, see [llms.txt](https://docs.volaris.games/volsai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.volaris.games/volsai/linkolnos/documentation.md). # Documentation 🔗 [\[GitHub Repository\]](https://github.com/VolarisGames/LinkolnOS) > Open-source launchpad for deploying real-time, knowledge-aware AI agents on Telegram. LinkolnOS lets you spin up a Telegram bot that fetches live content from websites you control, talks to an OpenAI model, and remembers the conversation. Admins manage the knowledge base from inside Telegram — no dashboard required. [![CI](https://github.com/VolarisAI/LinkolnOS/actions/workflows/ci.yml/badge.svg)](https://github.com/VolarisAI/LinkolnOS/actions/workflows/ci.yml) [![License: MIT](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667) [![Node](https://camo.githubusercontent.com/8f0aa01709dafbe9f00aba61e321d4549bf3de348f23e14f1df46fd6edc2c69b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6e6f64652d25334525334431382d627269676874677265656e2e737667)](https://camo.githubusercontent.com/8f0aa01709dafbe9f00aba61e321d4549bf3de348f23e14f1df46fd6edc2c69b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6e6f64652d25334525334431382d627269676874677265656e2e737667) [![Status: beta](https://camo.githubusercontent.com/1651d68ef49a0de0fabf4e2f1059528b04e2a7f0bfdf09fd1ede41a56653fe08/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d626574612d79656c6c6f772e737667)](https://camo.githubusercontent.com/1651d68ef49a0de0fabf4e2f1059528b04e2a7f0bfdf09fd1ede41a56653fe08/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d626574612d79656c6c6f772e737667) *** ### Features * **Telegram-native** — users chat directly in Telegram, no extra app * **Live website crawling** — bot pulls fresh content per query (axios + cheerio) * **Per-project knowledge bases** — admins add/remove source URLs via bot commands * **OpenAI-backed responses** — configurable model, temperature, and token budget * **Persisted state** — projects, admin passwords, websites, and conversation history all in Postgres (survives restarts) * **Polling or webhook mode** — polling auto-enabled for local dev (no tunnel needed); webhook mode for production * **Two access modes** — Admin mode (manage knowledge) and User mode (ask questions) * **Customizable personality** — edit `personality.json` to change tone and capabilities *** ### Requirements * **Node.js ≥ 18** * **PostgreSQL** running locally or remotely (any recent version) * **Telegram bot token** — get one from [@BotFather](https://t.me/BotFather) * **OpenAI API key** — from [platform.openai.com](https://platform.openai.com/api-keys) * **A public HTTPS URL** — *only required for webhook (production) mode*. Local dev runs in polling mode automatically. *** ### Quickstart (local dev, polling mode) ``` # 1. Clone & install git clone https://github.com/VolarisAI/LinkolnOS.git cd LinkolnOS npm install # 2. Configure cp .env.example .env # Edit .env: TELEGRAM_BOT_TOKEN, OPENAI_API_KEY, ADMIN_PASSWORD, DB_* values. # Leave WEBHOOK_URL blank to run in polling mode (no tunnel needed). # 3. Make sure Postgres is reachable with the credentials in .env. # LinkolnOS auto-creates its tables on first run. # 4. Start npm start ``` If anything is missing from `.env`, the app exits with a friendly list of what to fix. Once running, open your bot in Telegram and send `/start` to create your first project. #### Running tests ``` npm test ``` *** ### Configuration All configuration lives in `.env`. See [`.env.example`](https://github.com/VolarisAI/LinkolnOS/blob/master/.env.example) for the canonical list. | Variable | Required | Default | Purpose | | ------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | `TELEGRAM_BOT_TOKEN` | ✅ | — | From @BotFather | | `ADMIN_PASSWORD` | ✅ | — | Password admins type to unlock admin commands | | `OPENAI_API_KEY` | ✅ | — | Your OpenAI API key | | `OPENAI_MODEL` | ⬜ | `gpt-4o-mini` | Any chat-completions model | | `OPENAI_MAX_TOKENS` | ⬜ | `500` | Max response length | | `OPENAI_TEMPERATURE` | ⬜ | `0.9` | 0.0 = deterministic, 2.0 = wild | | `DB_USER` / `DB_HOST` / `DB_NAME` / `DB_PASSWORD` / `DB_PORT` | ✅ | — | Postgres connection | | `DB_SSL` | ⬜ | `false` | Set `true` for hosted Postgres that requires SSL (Render, Heroku, Supabase). Leave `false` for local Postgres. | | `WEBHOOK_URL` | ⬜ | — | Public HTTPS URL (e.g. `https://yourapp.onrender.com`). **Leave blank for polling mode.** Set it to switch to webhook mode. | | `PORT` | ⬜ | `3000` | HTTP port for the webhook server (only used in webhook mode) | | `MAX_WEBSITES` | ⬜ | `50` | Per-project URL limit (documented; not enforced yet) | *** ### Architecture ``` ┌──────────────┐ Telegram ──► │ app.js │ ──► Polling (dev) OR Express webhook (prod) │ (router) │ └──┬───────────┘ │ ┌─────────────┼─────────────────────────────┐ ▼ ▼ ▼ commands/ crawler.js llm.js (admin + (axios + cheerio, (OpenAI client, user verbs) pulls live page content) personality.json) │ │ │ └─────────────┴───► stateManager.js (in-memory cache, write-through to Postgres) │ ▼ db.js (Postgres — projects + conversation history) ``` **Key files:** * `app.js` — entry point, mode detection (polling vs webhook), top-level message routing * `commands/` — admin + user command handlers * `crawler.js` — website fetching and content extraction * `llm.js` — OpenAI chat-completions integration and personality loading * `stateManager.js` — read-through cache backed by Postgres; sync reads, async writes * `db.js` — Postgres schema (projects + conversations) and pool * `personality.json` — bot's name, bio, capabilities (editable) * `test/` — unit tests run via Node's built-in `node:test` * `.github/workflows/ci.yml` — runs lint + tests on Node 18, 20, 22 for every PR *** ### Deployment **Local development** — polling mode is automatic when `WEBHOOK_URL` is unset. Just run `npm start`. **Production** — set `WEBHOOK_URL` to a public HTTPS URL and the bot switches to webhook mode. Recommended hosts: * **Render**, **Railway**, **Fly.io** — set `WEBHOOK_URL` to your service URL; the bot binds to `$PORT` (Render sets this automatically) * **AWS / GCP / your own VPS** — terminate TLS in front of the Node process * **Local "production-like" testing** — use [ngrok](https://ngrok.com/) or [cloudflared](https://github.com/cloudflare/cloudflared) to expose `http://localhost:3000` and put that URL in `WEBHOOK_URL` Use a process manager (PM2, systemd, your platform's restart policy) so the bot recovers from crashes. The app handles `SIGTERM`/`SIGINT` gracefully — webhook is removed from Telegram and Postgres pool is closed before exit. *** ### Usage Inside Telegram: * `/start` — Creates a new project (first time) or resumes your existing one * `/start ` — Deep-link into someone else's project as a user * `/help` — Show command reference * **For Admin** button → enter `ADMIN_PASSWORD` → manage websites, change password, delete the agent * **Restart Conversation** button — clears your conversation history *** ### Known Limitations Be honest with yourself before deploying this in production: * **Shared admin password per project.** No per-user admin auth — anyone with the password is admin. * **Every user message re-crawls every URL.** No caching. If a project has 5 sites × 3 subpages each, that's 20 HTTP fetches per Telegram message. Slow + bandwidth-heavy + may hit rate limits on the source sites. Caching is on the roadmap. * **Keyword filtering before LLM is naive substring matching.** Works for simple queries; misses paraphrases. Vector search would be a real improvement. * **No file-upload support.** Knowledge base is web pages only — no PDF, CSV, DOCX yet. *** ### Roadmap * [x] ~~Persist `stateManager` to Postgres so projects survive restarts~~ ✅ (Phase 3) * [x] ~~Optional polling mode for local development~~ ✅ (Phase 3) * [x] ~~Smoke tests + CI on PRs~~ ✅ (Phase 3) * [x] ~~Proper chat-completions messages array (instead of flattened string)~~ ✅ (Phase 3) * [ ] In-memory crawler cache (5-min TTL) to cut latency and OpenAI token cost * [ ] Per-user admin roles instead of shared password * [ ] File-upload support (PDF, CSV, DOCX) for the knowledge base * [ ] Vector embeddings + similarity search instead of keyword substring match * [ ] Structured logging (Winston / Pino) * [ ] Rate limiting per chat ID * [ ] ESLint + Prettier configuration *** ### Contributing PRs welcome. See [CONTRIBUTING.md](https://github.com/VolarisAI/LinkolnOS/blob/master/CONTRIBUTING.md) for setup, branch naming, and review expectations. Security issues: please follow [SECURITY.md](https://github.com/VolarisAI/LinkolnOS/blob/master/SECURITY.md) — don't open a public issue. *** ### License [MIT](https://github.com/VolarisAI/LinkolnOS/blob/master/LICENSE) © 2026 Volaris Games The MIT license requires attribution: if you ship code derived from LinkolnOS, please keep the copyright notice in the source. A mention in your README is appreciated but not legally required. *** ### Acknowledgements * [OpenAI](https://openai.com/) for the LLM * [`node-telegram-bot-api`](https://github.com/yagop/node-telegram-bot-api) for the Telegram integration * [Cheerio](https://cheerio.js.org/) + [Axios](https://axios-http.com/) for the crawler * [PostgreSQL](https://www.postgresql.org/) for persistence #### Enjoy building with LinkolnOS!