A self-hosted agent that talks to you in Telegram, remembers, and builds its own automations.
Documentation · Install · Install guide · Report a bug
ganglion is an agent written in Go. You talk to it in Telegram; it remembers, searches, runs commands in a sandbox, and when a task repeats it writes a small program for it. That program, a reflex, is compiled to WebAssembly and then runs on a schedule without the model: the model is called for conversation and for exceptions, not for every tick.
The long-term shape is a network of nodes: a core that holds conversations and memory, edge runners next to devices, and workers where the model runtimes are. Today it is one process that carries all three roles.
flowchart LR
you([You in Telegram]) <--> agent[Agent<br/>model, memory, skills, tools]
agent -- "writes a module<br/>for a routine task" --> build[Build to WASM]
build -- "you approve" --> reflex[Reflex in wazero<br/>runs on a schedule]
reflex -- "reads and writes" --> cells[(State cells)]
outside[Outside services<br/>and devices] --> cells
reflex -- "notifies, or escalates<br/>an exception" --> agent
A reflex gets only the capabilities its manifest asks for, every build is versioned, and a bad version rolls back. State-changing actions of the agent are confirmed with a button.
Early, 0.x, no guarantees. One person builds it on weekends, with Claude writing most of the code. The repository is open so that people can read it, try it and report bugs; it is not a released product. Formats, commands and the configuration file change without notice, and an issue may wait for an answer. The public release is planned for a later phase (ADR-0082).
One node has been running the author's family bot since November 2026. The ganglion project shows the current state and plan.
| Telegram agent | Private chats and groups (in a group it answers only when addressed), an access list: strangers get no reply. |
| Models by purpose | The claude CLI on your own subscription, or any OpenAI-compatible API, chosen per purpose in one file. |
| Memory | Kept by topic in plain files; sessions, reminders and scheduled tasks. |
| Tools under policies | Web search and reading; host commands in a sandbox (Landlock, no new privileges, a clean environment); every state-changing action confirmed by a button. |
| Reflex modules | The agent writes a module in Rust, the node builds it to wasm32-wasip1 and, after you approve, runs it in wazero. Versioned, with rollback. |
| Skills | Procedures in Markdown the agent reads before it acts. |
| Operations | An encrypted secret store, one configuration file with a JSON schema, logs, a tool-call journal, /status, read-only diagnostics over MCP (ganglion mcp). |
Not built yet: nodes talking to each other (the network of the name), prebuilt binaries, updating a node from a release in the chat.
ganglion runs on Linux. Host commands and module builds need kernel 6.2
or later (Landlock). You need a Telegram bot token from
@BotFather, your Telegram user id, and access to
at least one model (the claude CLI or an OpenAI-compatible API key).
The Getting started
guide has every step in full; below is the short version.
Each release tag publishes an image for linux/amd64 and linux/arm64
(a Raspberry Pi): the node, Rust and the claude CLI, run as an
unprivileged user, with its data on a volume at /data. Pin a version
(0.1.0) or a line (0.1) instead of latest once you rely on it.
docker run -d --name ganglion --restart on-failure \
-v ganglion-data:/data \
-e TELEGRAM_BOT_TOKEN=... -e CLAUDE_CODE_OAUTH_TOKEN=... \
ghcr.io/igorrius/ganglion:latestThe settings file goes to /data/ganglion.yaml (see Configure below);
Install
has the details, and how to build the image yourself.
Needs Go 1.27; building modules also needs Rust with the wasm32-wasip1
target.
git clone https://github.com/igorrius/ganglion.git
cd ganglion
make build # ./bin/ganglion
./bin/ganglion versionOne file holds every setting and no secret. A secret is named there as
env:NAME (an environment variable) or store:NAME (the node's encrypted
store, filled with ganglion secret set NAME). The node keeps its database
beside the file.
cp ganglion.example.yaml ganglion.yaml
# In ganglion.yaml: set telegram.admin to telegram:user:<your Telegram id>
# and choose the providers and models you have.export TELEGRAM_BOT_TOKEN=... # plus the provider keys the file names
./bin/ganglion runWrite to your bot in Telegram. To have it build something, describe a routine task; it starts a module from one of two templates in examples/modules: a reader that brings an outside service's numbers into cells, and a reflex that reacts to cells and writes to you.
Running on a hosting platform: Deploying on Railway; most of it applies to any.
User guide: https://igorrius.github.io/ganglion/: install, configure, commands, modules, operations, troubleshooting.
| You want to | Read |
|---|---|
| Install and run a node | Getting started |
| Know every command and setting | Commands, Configuration reference |
| Fix something | Troubleshooting |
The engineering record lives in the repository, beside the code: docs index, the specification, architecture, decision records and conventions.
Bugs and ideas go to GitHub Issues; what is in work and what comes next is on the project board. Before a pull request, read CONTRIBUTING.md. A vulnerability is reported privately: see SECURITY.md.