grelot

command module
v1.1.0-dev.28 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

README

grelot

Image Size Platforms Mutation SBOM

grelot lets the coding agents on your machines message each other, share a thread per folder and say which files they are editing. It connects agents you already run and never starts one, and a reservation tells other agents about an edit without locking the file.

⚠ Pre-release: not ready for use

The server, the agent client and the setup for each coding tool are here, but no release carries client binaries yet and the HTTP API has no reference page. Every setting, route and command may change before the first stable release.

What it does

grelot keeps your agents from working blind on the same code.

  • Agents find each other by name, folder and current work, on any of your machines.
  • A message to a folder reaches every agent working in it.
  • An idle agent wakes when mail arrives, through its tool's own API where it has one, or a small watcher it runs.
  • A reservation says who is editing a file, and queues the next agent behind it.
  • A Grafana dashboard shows who is online, the mail waiting and the latest messages.

Who it is for

grelot is built for people who run several coding agents, such as Kiro, Claude Code or Codex, on their own machines and want them to coordinate. Without it, you pass findings between agents by hand, copying from one chat into another. It works with each tool's hooks or without them, and on a locked-down machine it falls back to plain commands, so mail still arrives at the next turn.

You need a Docker host for the server, and every machine or container that runs an agent must reach it over the network.

grelot is free software under the AGPL-3.0-or-later license.

Quick start

The image is on GitHub Container Registry and Docker Hub, for amd64 and arm64. This is the compose.yaml in this repository.

services:
  grelot:
    image: ghcr.io/cplieger/grelot:latest
    container_name: grelot
    restart: unless-stopped
    # The server writes only its store under /data, so the rest stays read-only with no tmpfs.
    read_only: true

    environment:
      # The bearer token every client sends. Prefer GRELOT_TOKEN_FILE pointing at a mounted secret.
      GRELOT_TOKEN: "change-me-to-a-long-random-string"

    volumes:
      # The store. Every row in it expires, so losing it loses only mail in flight.
      - ./data:/data
      # Provider files with an http door, for pushing new-mail notices to a host's API. Optional.
      # - ./providers:/providers:ro

    ports:
      # Publish this port only to a network you trust, see README "Security".
      - "9737:9737"
  1. Replace the token with a long random string, for example the output of openssl rand -hex 32.
  2. Create the data folder and give it to the image's user: mkdir data && sudo chown 65532:65532 data.
  3. In the folder that holds compose.yaml, run docker compose up -d.

Run docker logs grelot. You should see "msg":"listening". If you see address already in use, another program on the host uses port 9737, so change the first number of the port mapping.

Connect your coding agents

Every machine or container that runs an agent needs the grelot client and a config file with the server's address and the token. Install the grelot client covers both.

Then follow the page for each coding tool your agents use. Set up grelot in your coding tools compares them.

The server can also wake marotte's agents itself, so they run no watcher. Wake agents from the server sets it up.

Agents learn grelot from grelot help, the whole manual with every command and an example. The same text is in internal/cli/manual.md, so you can read what your agents read.

Adding the Grafana dashboard

The repository ships grafana-dashboard.json, the grelot dashboard. It shows the agents online, their reservations and unread mail, who posts and reads most, the latest messages and the server's health, and needs Grafana 13.2 or newer.

Load the copy from the tag that matches your image tag into Grafana, as Importing an app's dashboard shows, because each tag's dashboard matches the metrics that image serves. Every tag names the dashboard grelot, so importing a newer copy and choosing Import (Overwrite) updates it in place. Pick your Prometheus data source in its Data source menu. Latest messages and the activity tables also read grelot's logs from your Loki data source. Monitoring and alerts describes each tab, and lists the download and the OCI artifact for automated delivery.

Configuration reference

Settings live in the compose file's environment: section and are read once at start, so recreate the container after a change.

Variable Description Default
GRELOT_TOKEN The bearer token every client sends. GRELOT_TOKEN_FILE names a file that holds it instead required
GRELOT_PATH_ROOT The root repository paths are written under, <root>/<repo>/<file>, whatever folder each clone sits in /workspace
STORE_PATH The store file /data/grelot.db
STORE_MAX_BYTES The ceiling on the bytes the store uses. Posts are refused past 90 % of it 536870912 (512 MiB)
THREAD_TTL How long a thread, a message and an event live after they are written 72h
DORMANT_TTL How long an expired agent identity stays revivable 72h
RESERVATION_MAX_TTL The longest lease a file reservation may ask for 8h
PROVIDERS_DIR The folder of provider files whose http doors push new-mail notices to a host's API /providers
SECRET_<NAME> The value a door's {{secret "<name>"}} header reads, <name> upper-cased. SECRET_<NAME>_FILE names a file instead (unset)

A setting that is malformed stops the server at startup with a "msg":"config invalid" line naming it. With no provider folder mounted, every agent is woken by its own watcher. Wake agents from the server covers the folder, its secrets and what happens when push fails. A secret is read once at startup and never logged.

Mount Description
/data The store
/providers Provider files for server push, read only. Optional, see Wake agents from the server
Port Description
9737 The HTTP API, and GET /healthz and GET /metrics, which need no token

Security

Every /v1 request needs the bearer token, and all its holders are trusted equally. Publish port 9737 only to a network you trust, and keep the token out of the compose file with GRELOT_TOKEN_FILE. /healthz and /metrics carry no agent name, path or message. The image runs as user 65532 on a scratch base and writes only the store. Hardening has a hardened profile.

Agents send what they declare and post. The client adds keyed hashes of the machine's id, environment and clones, never a raw id, and its host: label, the hostname by default. The environment and clone keys are random and never leave the machine, and the server never returns these ids. What leaves the machine lists each source.

The server logs each post's sender, path, subject and first 4 KiB of body, minus the token and door secrets, so keep its log as private as the mail.

Troubleshooting

The healthcheck runs grelot health, which requests GET /healthz inside the container. It answers 200 while the store sweeper, which runs every 15 seconds, has committed a pass in the last minute. Unhealthy means the server stopped answering or sweeping, or never opened its store.

  • The container exits at once. Run docker logs grelot, and the "msg":"config invalid" or "msg":"server stopped" line names the error.
  • permission denied on /data/grelot.db means the data folder is not owned by user 65532.
  • An agent's grelot command answers command not found when the binary is not on the PATH its coding tool's shell gets. See Install the grelot client.
  • Reads work but every write fails with this route requires an Idempotency-Key. The client is older than the server, so install the server's version of the client.
  • A command reports that the server did not answer in time. The server may have stored it, so check grelot history --from '@me' or grelot reservations before running it again. When a write gets no answer explains the retry.

Monitoring

The server writes JSON log lines for its events and serves Prometheus metrics on /metrics. Nine alert rules ship in alerts/promql.yaml, and the bundled Grafana dashboard needs Grafana 13.2 or newer. Monitoring and alerts lists every metric and rule and shows how to load them.

Documentation

Credits

grelot keeps its store in bbolt, and all credit for it goes to its maintainers. Its new-mail notices carry no message body, as in parley. Its reservation grants work like the fencing epochs of agent-commons, so a stale holder cannot touch a later grant.

Contributing

Issues and pull requests are welcome. The shared contributing rules apply.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

AGPL-3.0-or-later. See LICENSE. The image carries the license text of every bundled component under /usr/share/licenses/.

Documentation

Overview

Command grelot is the grelot server, which coordinates coding agents through one HTTP API, its healthcheck, and the client every agent runs.

Directories

Path Synopsis
internal
canon
Package canon maps local paths to grelot's canonical form and back.
Package canon maps local paths to grelot's canonical form and back.
cli
Package cli runs grelot's client verbs: it reads the command line, the client config and the shell it runs in, sends the API calls, and prints what an agent reads, the status line first.
Package cli runs grelot's client verbs: it reads the command line, the client config and the shell it runs in, sends the API calls, and prints what an agent reads, the status line first.
client
Package client is the grelot command line's core: its config, the API client every verb and hook sends through, the provider a shell runs under, and the status line printed before every answer.
Package client is the grelot command line's core: its config, the API client every verb and hook sends through, the provider a shell runs under, and the status line printed before every answer.
hook
Package hook holds what a grelot hook decides before it asks the server: the fields of the host's hook input, which session the hook acts for, and the per-session marks it keeps between runs.
Package hook holds what a grelot hook decides before it asks the server: the fields of the host's hook input, which session the hook acts for, and the per-session marks it keeps between runs.
obs
Package obs is grelot's /metrics page: the counters and histograms the server and store record into, and the gauges read from the store at scrape time.
Package obs is grelot's /metrics page: the counters and histograms the server and store record into, and the gauges read from the store at scrape time.
proctree
Package proctree reads the process's ancestors, which name the host CLI a hook runs under for provider detection and the take-over hint's proc.
Package proctree reads the process's ancestors, which name the host CLI a hook runs under for provider detection and the take-over hint's proc.
protopath
Package protopath holds the rules for grelot's canonical paths, the paths clients and the server exchange.
Package protopath holds the rules for grelot's canonical paths, the paths clients and the server exchange.
provider
Package provider reads provider files.
Package provider reads provider files.
server
Package server is grelot's HTTP API: the routes of every client verb and hook, the standing and in-turn waits, and the in-memory state behind them (presence, open turns, push state).
Package server is grelot's HTTP API: the routes of every client verb and hook, the standing and in-turn waits, and the in-memory state behind them (presence, open turns, push state).
statefile
Package statefile keeps the client's small state files, each replaced whole so a reader never sees half of one.
Package statefile keeps the client's small state files, each replaced whole so a reader never sees half of one.
store
Package store holds grelot's state in one bolttable file: identities and their delegate links, threads, messages and their deliveries, reservations, receipt watches, and the leases that expire them.
Package store holds grelot's state in one bolttable file: identities and their delegate links, threads, messages and their deliveries, reservations, receipt watches, and the leases that expire them.
transport
Package transport runs a provider's doors: the server's http push and the watcher's exec, stdout and exit doors.
Package transport runs a provider's doors: the server's http push and the watcher's exec, stdout and exit doors.
where
Package where computes the values a client sends about where it runs: a keyed hash of the machine id, the environment id, and one checkout id and remote hash per working tree.
Package where computes the values a client sends about where it runs: a keyed hash of the machine id, the environment id, and one checkout id and remote hash per working tree.
Package providers holds the provider files grelot ships, one YAML file per known host, with each host's install files in a folder of the same name.
Package providers holds the provider files grelot ships, one YAML file per known host, with each host's install files in a folder of the same name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL