echo

A small service. A visible difference.

Give your events
a little light.

Turn a webhook into something you can see. echo connects your apps to an 8×8 LED matrix, so a notification becomes a moment of light.

Get echo for Linux See how it works

Self-hosted. Built in Go. Made for your LAN.

echo / matrix preview8 × 8
Notification badgePreview
Illustrative preview, not a connected device. Notification geometry comes from echo’s built-in renderer; other patterns are sample pixel art.
HTTP in. Light out.ESP8266 · 8×8 matrixLinux · Raspberry Pi · DockerOpen source, on GitHub

Small pixels.
Plenty of possibilities.

A quiet background. A timely alert. A custom pattern.
Let your display do more than stay on.

Your events, your rules.

Send JSON from Home Assistant, n8n, or any webhook source. YAML rules choose the animation, priority, and what happens after it plays.

Home automationDeploy notificationsMonitoring alerts
Explore the example rules

One service. Several displays.

Each matrix gets its own queue, connection settings, and idle background. Keep the office and living room in their own rhythm.

Back to the background.

Restore the configured idle animation after a notification. Automatic reconnect and heartbeat probes handle interrupted device connections.

Draw it in YAML.

Author 8×8 frames with a palette and simple text rows. No firmware edit needed for your own pixel art.

Let the device do the work.

Trigger 22 firmware effects, or upload up to 8 frames to loop on the panel without a network trip per frame.

See what’s happening.

Prometheus metrics, liveness and readiness endpoints, and interactive API docs make operation less of a guessing game.

A short trip
from event to light.

echo runs on a Linux machine or Raspberry Pi on the same network as your display. Your apps speak HTTP; echo handles the matrix’s binary TCP protocol.

  1. 1

    An app sends an event.

    A small JSON request arrives over HTTP.

  2. 2

    echo finds the right rule.

    The device’s scheduler queues the animation.

  3. 3

    Your matrix lights up.

    Playback finishes, then idle state returns when configured.

Send your first notification
curl -X POST \
  http://localhost:8080/api/v1/devices/living-room/notify \
  -H 'Content-Type: application/json' \
  -d '{"message":"Build finished","duration":"3s"}'

The matching rule plays an animation. The message is event data, not scrolling text on the display.

Explore the HTTP API

Your next light show
starts on Linux.

Run in Docker or build a native binary.
No cloud account. Your setup, your control.

Start with the essentials.

You’ll need Git, a Linux host, and a compatible ESP8266 matrix controller on your LAN. Choose Docker or Go 1.26.9+.

  1. Get the source and config.

    Bash · first steps
    git clone https://github.com/worxbend/echo.git
cd echo
cp configs/config.example.yaml configs/config.yaml

  2. Point echo at your display.

    Edit devices.living-room.host in configs/config.yaml. The example animation and rules files are already referenced.

  3. Set a private admin token.

    In Bash, read a token without saving it in shell history. Use this same terminal for the Docker or native commands below.

    Bash · private input
    read -rsp 'Admin token: ' MATRIX_PROXY_ADMIN_TOKEN
printf '\n'
export MATRIX_PROXY_ADMIN_TOKEN
Recommended

Run with Docker.

Build the current checkout with Docker’s multi-stage build. Go stays in the builder, not on your host.

Bash · after setup
docker build -t echo-local .
docker run -d --name echo \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  --mount type=bind,source="$PWD/configs",target=/app/configs,readonly \
  -e MATRIX_PROXY_ADMIN_TOKEN \
  echo-local

HTTP is published on localhost only. The container connects to your matrix over the LAN. Read the API access notes before exposing it elsewhere.

Build a native Linux binary

Prefer no container? Install Go 1.26.9 or newer, complete the three setup steps first, then build and run:

Bash · after setup
go build -o bin/matrix-proxy ./cmd/matrix-proxy
./bin/matrix-proxy -config configs/config.yaml

The native example listens on all interfaces as configured. Admin routes require the token; event ingress is intentionally unauthenticated. Keep it on a trusted LAN or behind a suitable gateway.

Check that echo is alive.

curl http://localhost:8080/healthz

Look for {"status":"ok"}. Open http://localhost:8080/docs for the API explorer. /readyz returns 503 until the matrix and workers are ready.

Looking for a pre-built image? Browse the container package. The source-build instructions above match the current checkout; no downloadable native release is promised.

A few things
worth knowing.

Ask on GitHub
Is echo the firmware for my display?

No. echo is the HTTP service that controls a compatible ESP8266 8×8 matrix over TCP. Your panel needs compatible firmware and a reachable network address. See the wire protocol before connecting a different controller.

Can I try it without a matrix?

Yes. The HTTP service starts, exposes the API and animation catalog, and retries the device connection. Liveness can be healthy while readiness returns 503. Display operations need reachable hardware.

Can I control individual pixels?

Yes. The API exposes pixel, fill, brightness, clear, and panel controls. With an idle background enabled, manual changes can be restored to that background. To keep the panel dark while retaining its image, disable panel output rather than clearing it.

Should I put it on the public internet?

Not directly. Admin routes require a bearer token on a non-loopback bind, but notification and event ingress, metrics, and health probes are intentionally unauthenticated. Use a trusted network or add access control at your gateway.

Make the invisible
a little more visible.

A webhook, a rule, and 64 pixels. Start there.

Install echo