pashifika/omp-relayd repository overview

⁠OMP Relay

A small self-hosted relay that routes work between named Oh My Pi sessions. Two OMP terminals hand tasks to each other without sharing a process or a terminal: this daemon routes MessagePack frames between named peers in memory, and the repository's OMP extension turns an inbound message into a follow-up turn on the receiving side.

Source, protocol reference and client setup: github.com/pashifika/omp-relayd⁠

⁠Read this before you run it

The transport is plain TCP with no authentication and no encryption. Anyone who can reach the port can join a room, list peers, and send messages as any name they choose.

Run it on a trusted host, or on a trusted private network. Do not publish the port to the public Internet. There is no public mode, and adding one is not a configuration option — mutual TLS is a later release.

The image reflects that stance: it publishes port 7788 inside the container only, runs as an unprivileged relay user, reads no configuration file, and keeps no message history — no queue for an absent peer, no replay after a reconnect. Restricting who can reach it is the published port's job. That one port carries both the frame protocol and attachment transfer, so exposure is a single decision, with no second port to reason about.

⁠What it holds on disk

Routing is in memory and stays there. Attachments are the exception, and they are why every command that runs the relay mounts a writable /tmp.

A message body is capped at 65024 bytes. Anything larger — a diff, a captured test run, a build log — is uploaded to the relay and referenced by the message that carries it. That is a bounded temporary store rather than persistence: every payload is removed when its room's last peer leaves, when its two-hour lifetime elapses, or at startup, and nothing survives a restart.

Without somewhere to write it, a read-only container starts and immediately exits:

ERROR omp_relayd: could not open the payload store base=/tmp/omp-relayd error=Read-only file system (os error 30)

tmpfs is RAM-backed, so size=320m bounds memory as well as bytes held. It sits above the relay's own 256 MiB ceiling deliberately, so a sender meets the relay's clean refusal rather than an I/O error from a full filesystem. To spend disk instead, mount a sized filesystem at /tmp — the relay reads TMPDIR and needs no other configuration. A named volume is the wrong shape here: it would outlive the container to hold data that must not persist.

⁠Run it

The safe minimum binds the published port to loopback, so reaching the relay requires being on the host:

docker run -d --name omp-relay \
  -p 127.0.0.1:7788:7788 \
  --read-only --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,size=320m,mode=1777 \
  pashifika/omp-relayd:0.2.0

To reach it from a trusted private network, publish it on one specific private address — never 0.0.0.0:

docker run -d --name omp-relay -p 192.168.1.10:7788:7788 \
  --read-only --cap-drop ALL --security-opt no-new-privileges:true \
  --tmpfs /tmp:rw,noexec,nosuid,size=320m,mode=1777 \
  pashifika/omp-relayd:0.2.0

The repository ships a compose.yml that does the same with the hardening already applied, and a scripts/setup-client.sh that writes both client configuration files and installs the collaboration skill.

⁠Configuration

The relay takes an address, and nothing else. There is no configuration file.

0.0.0.0 inside the container is deliberate: a container listening only on its own loopback would be unreachable even from its host, so exposure is decided by how you publish the port.

docker run --rm pashifika/omp-relayd:0.2.0 --help prints the same summary, and --version prints the build's version.

Logs are structured and carry room, peer, frame type, message identifier and payload size — never message bodies.

⁠Tags

Prefer a version tag in anything you deploy.

⁠Architectures

linux/amd64 and linux/arm64, each compiled natively for its own architecture and published under one manifest list, so a plain docker pull selects the right one without naming a platform.

⁠Where these images come from

Every image is built and pushed by the repository's Publish workflow from a manual dispatch on main, on GitHub's own runners. The sha- tag names the commit, and the workflow run that produced a digest is discoverable in the repository's run history. No image here is built or pushed from a workstation.

⁠License

MIT. See LICENSE⁠.