Installation
Docker Compose (Recommended)
Section titled “Docker Compose (Recommended)”The simplest way to try Sparrow. No clone, no secrets, no .env needed:
curl -O https://raw.githubusercontent.com/sarathsp06/sparrow/main/deploy/docker-compose.ymldocker compose up -d[!NOTE] This Compose file is for local evaluation – open API, a well-known encryption key, and the port bound to
127.0.0.1only. For a real deployment, see Production Deployment.
| Endpoint | URL |
|---|---|
| Web UI | http://localhost:8080 |
| REST API | http://localhost:8080 |
If port 8080 is taken, SPARROW_PORT=8090 docker compose up -d publishes the
server on http://localhost:8090 instead.
Open the web UI first. Registering event types and webhooks, pushing test
events and inspecting deliveries can all be done there, and it is the quickest
way to see how Sparrow works. The Quickstart
walks through the same steps in the UI and with curl.
To stop:
docker compose down # stop containersdocker compose down -v # stop and delete dataBuild from Source
Section titled “Build from Source”Prerequisites
Section titled “Prerequisites”- Go 1.27.4+ (the version in
go.mod) - Node.js 22+ (for web UI)
- PostgreSQL 15+
make build-with-uimake buildecho "DATABASE_URL=postgres://sparrow:sparrow@localhost:5432/sparrow?sslmode=disable" > .env# 32 cryptographically random bytes, hex-encoded as 64 charsecho "SPARROW_ENCRYPTION_KEYS=main=$(openssl rand -hex 32)" >> .envecho "SPARROW_ENCRYPTION_PRIMARY_KEY_ID=main" >> .env
make migrate # apply schemamake run # go run ./cmd/server, SPARROW_SERVE_UI=true; loads .env automaticallyNo local Postgres yet? make dev-db starts one (Docker) on the DATABASE_URL above. Without a .env, make run and make migrate default to that database and a dev-only all-zeros keyring; anything set in the shell or .env takes precedence.
For UI hot reload, run make run in one terminal and make run-web (cd web && npm run dev, served at localhost:5173) in another.
To run the full stack in containers instead, rebuilding from source on every change:
make docker-dev # docker compose -f docker-compose.dev.yml up -d --buildmake docker-purge # tear down, including volumesPre-built Binaries
Section titled “Pre-built Binaries”Every release ships cross-compiled binaries on the GitHub releases page — no Go toolchain required. Download the archive for your platform, extract it, and run:
- CLI — the
sparrowcommand-line tool, in thesparrow-cli-*archive - Server — the Sparrow server, in the
sparrow-*archive - Satellites — the
sparrow-sourcesandsparrow-sinksbinaries
Binaries are built for macOS and Linux (amd64 + arm64) and Windows (amd64).
--version prints the version of sparrow-server, sparrow-sinks and
sparrow-sources. Each release also carries checksums.txt with a keyless
cosign bundle (checksums.txt.sigstore.json), an SPDX SBOM per archive, and
the openapi.yaml/openapi.json of that version. Verify the checksums file
with:
cosign verify-blob --bundle checksums.txt.sigstore.json \ --certificate-identity-regexp '^https://github.com/sarathsp06/sparrow/' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ checksums.txtsha256sum --check --ignore-missing checksums.txtvX.Y.Z-rc.N tags are published as pre-releases and never move the
latest image tag.
To build from source instead:
make build-allDocker Image
Section titled “Docker Image”Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry:
Latest Docker release: ghcr.io/sarathsp06/sparrow:latest.
docker pull ghcr.io/sarathsp06/sparrow:latestThe Dockerfile uses a 3-stage build:
- Frontend (
node:24-alpine): Builds the SvelteKit UI - Backend (
golang:1.27.4-alpine): Compiles Go binaries with embedded UI - Runtime (
distroless/static-debian12:nonroot): Minimal production image