Install¶
From a container image¶
Each release is published as an image for linux/amd64 and linux/arm64 (a Raspberry Pi 4 or 5 with a 64-bit system):
docker pull ghcr.io/igorrius/ganglion:latest
The tags are:
| Tag | Points at |
|---|---|
latest |
The newest release |
<major>.<minor>, for example 0.1 |
The newest release of that line |
<version>, for example 0.1.0 |
Exactly that release; it never moves |
In 0.x a new minor version can change the configuration or stored formats, so pin a line or a version once you rely on the node. The package page lists every published version. ganglion version inside the container prints the release tag.
The image is about 1.2 GB. Most of it is the Rust toolchain that module builds need. It also holds the claude CLI.
To check that an image was built by the project's release workflow from the repository, use the GitHub CLI:
gh attestation verify oci://ghcr.io/igorrius/ganglion:latest -R igorrius/ganglion
Build the image yourself¶
Build it from a clone when you want unreleased code or an image without the claude CLI (--build-arg CLAUDE_CLI=off):
git clone https://github.com/igorrius/ganglion.git
cd ganglion
docker build -t ganglion .
Then use ganglion instead of ghcr.io/igorrius/ganglion:latest in the commands below.
Run it¶
The node keeps all its data in /data. Mount a volume there and pass your settings as environment variables:
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:latest
Things to know:
- The node runs as the user
ganglion, uid 10001. If you start the container as root, it hands/dataover to that user and drops privileges. If you start it with--user 10001, the volume must already belong to uid 10001. - Do not mount a single file (such as
ganglion.yaml) into the container. The node rewrites its configuration file, which needs a directory. Put the file inside/data. TELEGRAM_BOT_TOKENis the bot token.CLAUDE_CODE_OAUTH_TOKENis the login for theclaudeCLI (see Models). For an OpenAI-compatible service, pass the key variable your configuration names, for exampleOPENROUTER_API_KEY.- Set
telegram.adminin/data/ganglion.yamlbefore the first conversation. See Configure. --restart on-failurematters for/restart: the node then exits with code 75, and nothing in the image starts it again by itself.- Run any command that touches
/dataas uid 10001, never as root. A file created by root there can lock the node out.
docker exec -u 10001 ganglion ganglion secret list --db /data/ganglion.db
To set a secret this way, add -i to docker exec so the value reaches standard input.
From source¶
git clone https://github.com/igorrius/ganglion.git
cd ganglion
make build
./bin/ganglion version
make build writes the program to bin/ganglion. ganglion version --json prints the version in a form you can paste into a bug report.
Next: Configure.