ganglion user guide¶
ganglion is a self-hosted agent that you talk to in Telegram. It remembers what you tell it, searches the web, runs commands on your machine inside a sandbox, and asks you to press a button before it changes anything.
When a task repeats, the agent 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. This keeps routine work fast, cheap and predictable.
How it works¶
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.
What works today¶
- A Telegram agent for private chats and groups. In a group it answers only when addressed. Strangers get no reply.
- Models chosen per purpose: the
claudeCLI on your own subscription, or any OpenAI-compatible API. - Memory kept by topic in plain files, sessions you can resume, reminders and scheduled tasks.
- Web search and page reading, and host commands in a sandbox. Every action that changes something is confirmed with a button.
- Reflex modules the agent writes, builds and runs after you approve them, with versions and rollback.
- An encrypted secret store, one configuration file, logs,
/statusand read-only diagnostics.
Not built yet: nodes talking to each other, prebuilt binaries, and updating a node from inside the chat.
Status: 0.x¶
ganglion is early software. There are no guarantees. Commands, the configuration file and stored formats can change without notice, and you may need to adjust your setup after an update. Read the release notes in the repository before you update, and keep a backup.
Where to go next¶
- Requirements: what you need before you start.
- Install: from a container image or from source.
- Configure: the minimum settings and how secrets work.
- Your first conversation: run the node and say hello.
Then read how to talk to the bot, the command list and how to ask for a module. If something goes wrong, see Troubleshooting.