svetekllc/casper-sidecar repository overview

⁠Casper Sidecar

casper-sidecar is the JSON-RPC, REST, and SSE API layer for the Casper Network. Starting with Casper node 2.0 ("Condor"), the node itself no longer serves JSON-RPC directly — casper-sidecar connects to a local casper-node's binary port and exposes JSON-RPC (/rpc), a REST API, and an SSE event stream on top of it.

This image is built directly from the official casper-network/casper-sidecar⁠ source (not repackaged from a third-party binary), on a minimal Debian base.

⁠Supported tags

• v2.1.0 — built from casper-sidecar v2.1.0⁠

⁠Quick start

casper-sidecar is designed to run as a true sidecar: alongside a casper-node container, sharing its network namespace, so it can reach the node's binary port over 127.0.0.1.

# 1. Start your casper-node container first (see svetekllc/casper-node-launcher), e.g. named "casper-node"

# 2. Prepare a config.toml on the host (see "Configuration" below), then run the sidecar
#    attached to the node's network namespace:
docker run -d \
  --name casper-sidecar \
  --network container:casper-node \
  -v /path/to/config.toml:/etc/casper-sidecar/config.toml:ro \
  -v casper-sidecar-data:/var/lib/casper-sidecar \
  --restart unless-stopped \
  svetekllc/casper-sidecar:v2.1.0 \
  --path-to-config /etc/casper-sidecar/config.toml

Verify it's serving JSON-RPC:

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"info_get_status","params":[]}' \
  http://127.0.0.1:7777/rpc

⁠Configuration

Mount a config.toml at /etc/casper-sidecar/config.toml (path is passed explicitly via --path-to-config/-p). Minimal example for a co-located node (same network namespace, binary port 7779, REST 8888, SSE 9999):

[rpc_server.main_server]
enable_server = true
ip_address = "0.0.0.0"
port = 7777

[rpc_server.node_client]
ip_address = "127.0.0.1"
port = 7779

[rpc_server.node_client.exponential_backoff]
initial_delay_ms = 1000
max_delay_ms = 32000
coefficient = 2
max_attempts = 30

[sse_server]
enable_server = true
disable_event_persistence = false

[[sse_server.connections]]
ip_address = "127.0.0.1"
sse_port = 9999
rest_port = 8888
allow_partial_connection = true

[sse_server.event_stream_server]
port = 19999

[storage]
storage_folder = "/var/lib/casper-sidecar"

[storage.sqlite_config]
enabled = true
file_name = "sqlite_database.db3"

ip_address fields are parsed as literal IP addresses, not hostnames — if the sidecar does not share the node's network namespace, it must reach the node via a routable IP.

⁠Ports

Only 7777 needs to be reachable by RPC clients.

⁠Volumes

• /etc/casper-sidecar — mount your config.toml here (read-only recommended)
• /var/lib/casper-sidecar — SQLite storage for indexed event data; persist across restarts

⁠Source

• Built from casper-network/casper-sidecar⁠
• Base images: rust:1.91.0-trixie (build) / debian:trixie-slim (runtime)
• License: Apache-2.0 (upstream)