The API behind biga

A Go service that stores shared sessions and streams every change to the people watching.

Website · Documentation · API reference · Issues

---

The CLI uploads a snapshot of a folder and then small checkpoints as files change. The server keeps them in PostgreSQL and pushes each change to viewers over server-sent events. Only the client that created a session can write to it; a link lets people watch, nothing more.

Get started

Run the image

docker run -p 8080:8080 \
  -e DATABASE_URL='postgres://biga:…@db:5432/biga' \
  -e BIGA_PUBLIC_URL=https://biga.example.com \
  -e BIGA_TRUSTED_PROXIES=private \
  ghcr.io/biga-sh/server:1

Build from source

You need Go 1.26 or newer and a PostgreSQL database.

make build                                        # ./biga-server
DATABASE_URL='postgres://…' ./biga-server

The server applies its database migrations on start, answers GET /healthz (process up) and GET /readyz (PostgreSQL and Redis reachable), and shuts down gracefully on SIGTERM. Route /api/sessions/* to it and everything else to the website. To run the whole stack at once, use biga-sh/docker.

Configuration

Variable	Purpose
DATABASE_URL	PostgreSQL connection string. Required.
BIGA_LISTEN	Addresses to serve on. Default :8080.
BIGA_PUBLIC_URL	Origin viewers open, used to build share links
BIGA_ACCESS_KEYS	When set, only holders of one of these keys can broadcast
BIGA_TRUSTED_PROXIES	Peers whose X-Forwarded-For is believed
BIGA_CORS_ORIGINS	Origins allowed to read the API from a browser
BIGA_RETENTION_DAYS	Days an ended session is kept. Default 30.
REDIS_URL	Shares live events and rate limits across instances. Unset runs single-instance.

Secrets can also be read from a file by appending _FILE to the name, which is how Docker and Kubernetes secrets are mounted. Every setting, including limits and TLS, is listed in configuration.

Development

make test       # unit tests with the race detector; database tests skip
make db         # throwaway PostgreSQL on 127.0.0.1:55432
make test-db    # every test, including the API against PostgreSQL
make lint       # golangci-lint
make vuln       # govulncheck

Documentation

• Architecture
• API reference
• Configuration
• Self-hosting
• Threat model

Repositories

Repository	What it is
cli	The biga command. Watches a folder and streams every save.
server	The Go API. Stores sessions and streams updates to viewers.
website	The site, the live viewer and the documentation.
docker	Self-hosting: the whole stack with Docker Compose.

Contributing

Bug reports, focused fixes and pull requests are welcome. Read the contributing guide before you start, and report vulnerabilities privately as described in the security policy, not in a public issue.

License

biga is MIT licensed.

---

_{biga · Made for people who teach, pair and build in public.}