Installation

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.yml
docker 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.1 only. For a real deployment, see Production Deployment.

Endpoint	URL
Web UI	http://localhost:8080
REST API	http://localhost:8080

To stop:

docker compose down        # stop containers
docker compose down -v     # stop and delete data

Build from Source

Prerequisites

• Go 1.26+
• Node.js 22+ (for web UI)
• PostgreSQL 15+

Build

With UI

make build-with-ui

Server Only

make build

Run

echo "DATABASE_URL=postgres://sparrow:sparrow@localhost:5432/sparrow?sslmode=disable" > .env
# 32 cryptographically random bytes, hex-encoded as 64 chars
echo "SPARROW_ENCRYPTION_KEYS=main=$(openssl rand -hex 32)" >> .env
echo "SPARROW_ENCRYPTION_PRIMARY_KEY_ID=main" >> .env

make migrate   # apply schema
make run       # go run ./cmd/server, SPARROW_SERVE_UI=true; loads .env automatically

No 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 --build
make docker-purge   # tear down, including volumes

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 sparrow command-line tool, in the sparrow-cli-* archive
• Server — the Sparrow server, in the sparrow-* archive
• Satellites — the sparrow-sources and sparrow-sinks binaries

Binaries are built for macOS and Linux (amd64 + arm64) and Windows (amd64).

To build from source instead:

make build-all

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:latest

The Dockerfile uses a 3-stage build:

1. Frontend (node:22-alpine): Builds the SvelteKit UI
2. Backend (golang:1.26-alpine): Compiles Go binaries with embedded UI
3. Runtime (distroless/static-debian12:nonroot): Minimal production image