Skip to content

Add HTTP serve mode for Terminus/BYOS support#1

Open
ingm4r wants to merge 1 commit intopythcon:masterfrom
ingm4r:feature/terminus-byos-support
Open

Add HTTP serve mode for Terminus/BYOS support#1
ingm4r wants to merge 1 commit intopythcon:masterfrom
ingm4r:feature/terminus-byos-support

Conversation

@ingm4r
Copy link

@ingm4r ingm4r commented Feb 8, 2026

Summary

  • Adds an optional --serve mode that starts a lightweight HTTP server (stdlib http.server, no new deps)
  • Terminus Extensions can poll /data/<instance-name> for JSON instead of relying on cloud webhooks
  • Adds SERVE_PORT env var for Docker, serve: config section for YAML
  • Adds last_updated_local field so Terminus templates work without trmnl.user.utc_offset
  • Webhook mode remains the default — fully backward compatible

Architecture

Current:  Servarr → Collector --POST JSON--> TRMNL Cloud webhook → device
New:      Servarr → Collector <--GET JSON--- Terminus Extension → device

Endpoints

Path Response
GET / {"instances": {"sonarr": "/data/sonarr", ...}}
GET /data/<name> Full merge_variables payload as JSON

Files changed

File Change
collector/trmnl_collector.py HTTP server, store_payload(), CLI args, last_updated_local
collector/Dockerfile SERVE_PORT env, EXPOSE 8080, entrypoint handling
collector/docker-compose.yml Commented example for Terminus port mapping
collector/config.example.yaml serve: section, webhook optional note
README.md Terminus/BYOS section with link to setup guide
docs/terminus.md Full setup guide for Terminus/BYOS users

Test plan

  • Unit tested HTTP server locally (start server, store payload, GET /, GET /data/sonarr, 404 handling)
  • Python syntax check passes
  • End-to-end tested with Terminus: collector → HTTP serve → Terminus Extension poll → screen render
  • Verify --dry-run still works
  • Verify webhook mode still works unchanged
  • Docker build and run with SERVE_PORT env var

🤖 Generated with Claude Code

Instead of pushing to TRMNL cloud webhooks, the collector can now run
an HTTP server that Terminus Extensions poll for JSON data. This enables
self-hosted Terminus users to use the Servarr dashboard without cloud
webhook endpoints.

- Add --serve, --port, --host CLI args and serve config section
- Add DataHandler HTTP server (stdlib, no new deps) serving cached
  payloads at /data/<instance-name>
- Add last_updated_local field for Terminus (lacks trmnl.user.utc_offset)
- Add SERVE_PORT env var and EXPOSE 8080 to Dockerfile
- Add docs/terminus.md setup guide
- Webhook mode remains default and fully backward compatible

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant