README
¶
snagbox
Self-hosted issue-intake service. A Telegram bot and HTTP API collect issues from anywhere they surface, drop them into per-project queues, and let coding agents (or humans) drain those queues in order. Designed to pair well with Obsidian-agent workflows where an agent needs a durable, structured inbox of things to fix.
Single Go binary, backed by Postgres and MinIO (S3) for attachments, with a small admin web UI for triage.
Quickstart
cp .env.example .env
# edit .env with real values
docker compose up -d
The service listens on PORT (default 8080).
API surface
| Endpoint | Description |
|---|---|
POST /api/v1/issues |
Submit a new issue |
GET /api/v1/queue |
Pull the next unacknowledged issue for a project |
POST /api/v1/issues/{id}/ack |
Acknowledge an issue as handled |
GET /api/v1/issues |
List issues, with filtering |
GET /api/v1/attachments/{id} |
Fetch an issue attachment |
GET /healthz |
Liveness/readiness check |
Reporting issues from your projects
Wiring a bot or web app to file issues into snagbox is a two-value setup
(SNAGBOX_URL + a project-scoped ingest token) plus one call. See
INTEGRATION.md for the full copy-paste guide.
- Go client:
client/—go get github.com/supercakecrumb/snagbox/client - TypeScript client:
clients/js/—@supercakecrumb/snagbox
Both are report-only and dependency-free. Draining the queue (the agent side) is plain HTTP.
Deployment
See DEPLOY.md.
License
MIT, see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client is a tiny, dependency-free Go SDK for reporting issues to a snagbox server.
|
Package client is a tiny, dependency-free Go SDK for reporting issues to a snagbox server. |
|
cmd
|
|
|
snagbox
command
Command snagbox is a self-hosted issue-intake service: a Telegram bot and HTTP API collect issues (text + photos) into per-project queues that agents drain independently.
|
Command snagbox is a self-hosted issue-intake service: a Telegram bot and HTTP API collect issues (text + photos) into per-project queues that agents drain independently. |
|
internal
|
|
|
api
Package api implements snagbox's HTTP API: issue ingestion (ingest-token auth) and the per-agent fan-out queue with acks (agent-token auth).
|
Package api implements snagbox's HTTP API: issue ingestion (ingest-token auth) and the per-agent fan-out queue with acks (agent-token auth). |
|
auth
Package auth provides Postgres-backed adapters for the msgr-authkit bot-first login-link flow, an admin Telegram-ID allowlist, session-cookie middleware, and a CSRF token helper for the web admin UI.
|
Package auth provides Postgres-backed adapters for the msgr-authkit bot-first login-link flow, an admin Telegram-ID allowlist, session-cookie middleware, and a CSRF token helper for the web admin UI. |
|
blob
Package blob stores and retrieves issue attachments in an S3-compatible object store (MinIO locally, any S3 provider in production).
|
Package blob stores and retrieves issue attachments in an S3-compatible object store (MinIO locally, any S3 provider in production). |
|
bot
Package bot runs snagbox's Telegram intake bot: allowlisted users send text and photos, which become inbox issues that can be tagged to a project via inline buttons.
|
Package bot runs snagbox's Telegram intake bot: allowlisted users send text and photos, which become inbox issues that can be tagged to a project via inline buttons. |
|
config
Package config loads snagbox configuration from environment variables.
|
Package config loads snagbox configuration from environment variables. |
|
digest
Package digest sends a once-a-day summary of the snagbox inbox to admins, so unsorted issues don't sit unnoticed between agent runs.
|
Package digest sends a once-a-day summary of the snagbox inbox to admins, so unsorted issues don't sit unnoticed between agent runs. |
|
store
Package store owns the Postgres connection pool and schema migrations.
|
Package store owns the Postgres connection pool and schema migrations. |
|
token
Package token generates and hashes opaque bearer tokens.
|
Package token generates and hashes opaque bearer tokens. |
|
web
Package web implements snagbox's server-rendered admin dashboard: managing projects, agents (queue consumers) and their per-project permissions, ingest tokens, and the Telegram user allowlist, plus an issue browser and the bot-first login-link redemption endpoint.
|
Package web implements snagbox's server-rendered admin dashboard: managing projects, agents (queue consumers) and their per-project permissions, ingest tokens, and the Telegram user allowlist, plus an issue browser and the bot-first login-link redemption endpoint. |
|
Package migrations embeds the goose SQL migration files so they can be applied from a single compiled binary without shipping loose .sql files.
|
Package migrations embeds the goose SQL migration files so they can be applied from a single compiled binary without shipping loose .sql files. |
Click to show internal directories.
Click to hide internal directories.