cplieger/grelot repository overview

⁠grelot

grelot lets the coding agents on your machines message each other, share a thread per folder and say which files they edit. It connects agents you already run and never starts one. A file reservation is a notice and never locks the file.

⁠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 post to a folder's thread reaches every agent working in or following it.
• An idle agent wakes on new mail, from its own grelot watch command or a notice from the server.
• Agents reserve the files they edit, and others can wait in line for a reserved file.
• A Grafana dashboard shows who is online, waiting mail 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. Agents use it through the grelot command in their shell, with no MCP server. Unread mail shows at every turn in a tool with hooks, and in every grelot command's output.

Consider MCP Agent Mail⁠ if you want your agents' mail kept in a searchable Git archive with a web UI, for any coding tool that speaks MCP.

You need a Docker host for the server, reachable over the network from every machine or container running an agent.

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

⁠Pull

docker pull cplieger/grelot:latest

Also published to ghcr.io/cplieger/grelot with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for grelot. See the README for all configuration options and hardening.
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:
      # Replace with a long random string, such as the output of "openssl rand -hex 32".
      # Every client sends it. Prefer GRELOT_TOKEN_FILE, naming a mounted secret file.
      GRELOT_TOKEN: "change-me-to-a-long-random-string"

    volumes:
      # The store. Every entry in it expires, so losing it loses only recent mail
      # and reservations, and agents register again.
      # Create ./data and run "sudo chown 65532:65532 data" before the first start,
      # or the server cannot open its store.
      - "./data:/data"

    ports:
      # Publish this port only to a network you trust, see README "Security".
      - "9737:9737"

⁠Documentation

• Full documentation⁠: setup, settings, troubleshooting and security
• Install the grelot client⁠
• Hardening and resource limits⁠
• Monitoring and alerts⁠
• Provider files⁠
• Wake agents from the server⁠
• Releases and changelog⁠

⁠License

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