GitHub
Step 01

Run the server

Docker
docker run -d -p 8080:8080 ghcr.io/reloading01/certstream-server-rust:latest
Script Linux, macOS
curl -fsSL https://raw.githubusercontent.com/\
reloading01/certstream-server-rust/main/install.sh | sh
Homebrew
brew install reloading01/tap/certstream-server-rust
Debian, Ubuntu
sudo dpkg -i certstream-server-rust_*_amd64.deb
sudo systemctl enable --now certstream-server-rust
Fedora, RHEL
sudo rpm -i certstream-server-rust-*.x86_64.rpm
sudo systemctl enable --now certstream-server-rust
Cargo
cargo install certstream-server-rust

The WebSocket stream is now available at ws://localhost:8080/. Packages and signed checksums are on the releases page. The .deb and .rpm packages install a systemd service and keep CT log positions across restarts.

Step 02

Connect

Python
import certstream

def callback(message, context):
    if message["message_type"] == "certificate_update":
        domains = message["data"]["leaf_cert"]["all_domains"]
        print(domains)

certstream.listen_for_events(callback, url="ws://localhost:8080/")
JavaScript
const ws = new WebSocket("ws://localhost:8080/");

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.message_type === "certificate_update") {
        console.log(data.data.leaf_cert.all_domains);
    }
};
cURL SSE
curl -N http://localhost:8080/sse
websocat
websocat ws://localhost:8080/
JavaScript domains-only
const ws = new WebSocket("ws://localhost:8080/domains-only");

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    // msg.message_type === "dns_entries"
    // msg.data is a flat array of strings, not a nested object
    if (msg.message_type === "dns_entries") {
        console.log(msg.data); // ["example.com", "www.example.com"]
    }
};

The /domains-only stream uses message_type: "dns_entries", and its data is a JSON array of domain names rather than a nested certificate object. For SSE, use curl -N "http://localhost:8080/sse?stream=domains".

Step 03

Persist state

Docker with state persistence
docker run -d \
  --name certstream \
  --restart unless-stopped \
  -p 8080:8080 \
  -v certstream-state:/data \
  -e CERTSTREAM_CT_LOG_STATE_FILE=/data/state.json \
  ghcr.io/reloading01/certstream-server-rust:latest

The state file stores the current CT log positions so the server can resume after a restart. See the API documentation for the full configuration reference.