Screenshot-a-Day

Screenshot-a-Day is a self-hosted visual history for websites. It captures reproducible screenshots on a schedule, compares changes, publishes galleries and GIF/WebM timelines, and can notify other tools through signed webhooks. An experimental MCP endpoint lets agents inspect projects and capture history or queue a new capture.

Website and documentation · Source and releases · Security reporting

Version 0.1.1 is the current stable patch release. The public archive demonstrates the static galleries published by the private released deployment; it does not expose the administrator UI, API, or worker. Read the v0.1.1 release notes, follow the original technical release runbook, or review the architecture decisions.

Quick start

Requirements: Docker with Compose and OpenSSL.

cp .env.example .env
openssl rand -base64 32
openssl rand -hex 32
openssl rand -hex 32

Put those three values into SAD_ENCRYPTION_KEY, SAD_SESSION_SECRET, and SAD_WORKER_TOKEN, then run:

chmod 600 .env
docker compose pull
docker compose up -d
docker compose logs api

Open http://localhost:4400/setup and use the one-time token from the API log. See the deployment guide, configuration reference, and security model before exposing the service publicly.

The Compose file pulls these versioned GitHub Container Registry images; Screenshot-a-Day is not published to npm or Docker Hub:

ghcr.io/arts-link/screenshot-a-day-api:0.1.1
ghcr.io/arts-link/screenshot-a-day-worker:0.1.1

To keep the home server private while hosting galleries elsewhere, configure a portable static publication target using the static publishing guide. Existing Vercel projects, Netlify sites, and dedicated SFTP roots are supported.

Experimental MCP endpoint

Remote MCP clients can connect to https://sad.example.com/mcp with a Screenshot-a-Day API bearer token. Grant read to inspect projects and captures and capture:trigger to queue captures; project-limited tokens retain the same boundary over MCP. A representative client entry is:

{
  "mcpServers": {
    "screenshot-a-day": {
      "type": "http",
      "url": "https://sad.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_SAD_API_TOKEN" }
    }
  }
}

Client configuration formats vary. See the API and MCP reference for the four v0.1 tools, authentication details, and compatibility status.

Supported platforms and v0.1 limitations

Published images support Docker-compatible linux/amd64 and linux/arm64 hosts. Docker Desktop can run them on supported macOS and Windows hosts through its Linux VM.

Version 0.1 uses SQLite and a local persistent volume, supports one API replica, and has forward-only database migrations. Pixel comparisons are profile-specific and limited to 16 million decoded pixels. Operators are responsible for TLS, storage, backups, monitoring, retention, and permission to capture each target. The self-hosted Screenshot-a-Day application includes no product telemetry; the separate project marketing site documents its anonymous, cookieless analytics in its privacy notice. Captures are not signed, certified, or tamper-proof; “signed” refers only to outbound webhook authentication.

Development

Source development and CI target Node.js 24 LTS and pnpm 11. Docker users do not need Node.js or pnpm on the host. The repository selects Node.js for mise, nvm, and tools that read .node-version; Corepack selects the exact pnpm release from package.json.

mise trust
mise install
mise exec -- corepack enable
mise exec -- zsh
pnpm install
pnpm check
pnpm dev

Review .mise.toml before running mise trust. With nvm, run nvm install, nvm use, and corepack enable instead. If this checkout was already used with another Node.js major, rebuild the ABI-specific SQLite addon with pnpm --filter @sad/api rebuild better-sqlite3 before running the checks.

Architecture and contributor details live in the development guide. The REST API serves interactive OpenAPI documentation at /docs/api; MCP is documented separately in the API and MCP reference.

Contributions require a DCO 1.1 sign-off; the project does not use a CLA. Report vulnerabilities privately as described in the security policy.

Versioning

The project follows Semantic Versioning, beginning at 0.1.0. All application packages and container images share one version.

License

Copyright (c) 2026 Arts-Link contributors. Screenshot-a-Day is free software licensed under the GNU Affero General Public License v3.0 or later.

The application displays a link to its corresponding source for remote users. There is no warranty; see LICENSE.