Development guide

Contributor-focused workflows: local setup details stay in SETUP.md at the repo root (Windows, troubleshooting, MCP/OpenClaw).

Clone and install

git clone https://github.com/healopss/opensre.git
cd opensre
make install

make install runs uv sync --frozen --extra dev and the analytics install helper. Use uv run opensre … from the repo root so you always hit this checkout’s .venv, not another opensre on your PATH.

opensre onboard
opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json

Quality gates (same as CI)

From the repo root:

make lint          # ruff check
make format-check  # ruff format --check (CI-enforced)
make typecheck     # mypy app/
make test-cov      # pytest + coverage (default unit suite)

One-shot (includes heavier test-full): make check. Before a PR, run at least make lint, make format-check, make typecheck, and make test-cov (see CONTRIBUTING.md).

Interactive shell: REPL watchdog demo

PR reviewers expect a visible demo (terminal log or screenshot) in the PR under Demo/Screenshot, not only tests. Copy the exact steps from this section into your PR description, then attach your terminal output or recording.

uv run opensre (TTY).
/trust on (or confirm the elevated-action prompt when running /watch).
/watch <pid> --max-cpu 80 — expect task … started. (use a real PID, e.g. the shell’s Python process).
/watches — table columns include id, pid, kind, status, thresholds, last sample.
/unwatch <task_id> or /cancel <task_id> — then /watches again; status should show cancelled.
Optional: lower --max-cpu so a threshold trips; after Telegram sends, the REPL prints one line: [task …] alarm fired: … (telegram delivered).

Automated equivalent (runs in make test-cov):
uv run pytest tests/cli/interactive_shell/test_watchdog_repl_e2e_demo.py -v --tb=short Longer transcript (optional): tests/cli/interactive_shell/repl_watchdog_demo.md.

VS Code dev container

The dev container is defined under .devcontainer/. It builds from .devcontainer/Dockerfile (Python 3.13), then postCreateCommand creates .venv-devcontainer and runs pip install -e '.[dev]' (not uv). Docker Desktop, OrbStack, Colima, or another compatible runtime must be available on the host.

Benchmark

make benchmark

To refresh README benchmark copy from cached results (no LLM calls): make benchmark-update-readme.

Deployment

Hosted runtime

Deploy this repository as a standard Python/FastAPI app using the repo Dockerfile or your host’s native Python workflow.
Set LLM_PROVIDER and the matching API key (for example ANTHROPIC_API_KEY, OPENAI_API_KEY — see .env.example).
Add integration and storage env vars your deployment needs.

Minimal LLM env:

export LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=...

Railway (self-hosted alternative)

Ensure the Railway project has Postgres and Redis and that the OpenSRE service has DATABASE_URI and REDIS_URI wired to them before deploying.

opensre deploy railway --project <project> --service <service> --yes

If the service never becomes healthy, confirm both URIs are set on the service.

Remote hosted ops (Railway)

After deploy:

opensre remote ops --provider railway --project <project> --service <service> status
opensre remote ops --provider railway --project <project> --service <service> logs --lines 200
opensre remote ops --provider railway --project <project> --service <service> logs --follow
opensre remote ops --provider railway --project <project> --service <service> restart --yes

OpenSRE remembers the last provider, so you can shorten to:

opensre remote ops status
opensre remote ops logs --follow

Telemetry and privacy

opensre ships with two telemetry stacks, both opt-out:

PostHog — anonymous product analytics (commands used, success/failure, rough runtime, CLI/Python/OS/arch, and limited command metadata).
Sentry — crashes and errors (stack traces, environment, release).

Events are tagged with entrypoint, opensre.runtime, and deployment_method. Sensitive headers, paths, and secret-shaped keys are scrubbed before send. A random install ID is stored under ~/.config/opensre/anonymous_id. PostHog distinct_id is scoped to that ID. Telemetry is off in GitHub Actions and pytest.

Kill-switch matrix

Env var	PostHog	Sentry
`OPENSRE_NO_TELEMETRY=1`	disabled	disabled
`DO_NOT_TRACK=1`	disabled	disabled
`OPENSRE_ANALYTICS_DISABLED=1`	disabled	unaffected
`OPENSRE_SENTRY_DISABLED=1`	unaffected	disabled

Full opt-out:

export OPENSRE_NO_TELEMETRY=1

Sentry DSN

Self-hosted users can set SENTRY_DSN to their project; unset uses the bundled default. SENTRY_DSN= (empty) drops events in before_send.

Deployment tagging

Set OPENSRE_DEPLOYMENT_METHOD to railway, ec2, vercel, or local (default local) to label Sentry events.

Local PostHog event log

By default, outbound PostHog payloads are also appended to ~/.config/opensre/posthog_events.txt (rotates at 1000 lines). Disable:

export OPENSRE_ANALYTICS_LOG_EVENTS=0

We do not collect alert contents, file contents, hostnames, credentials, raw CLI arguments, or PII by design.

Uptime monitoring

HealOps exposes a /health endpoint that checks both database and Redis connectivity and returns a 200 OK when all dependencies are healthy, or 503 Service Unavailable when any are down. Response shape:

{
  "ok": true,
  "version": "1.2.3",
  "llm_configured": true,
  "env": "production",
  "db": true,
  "redis": true
}

Better Uptime (recommended)

Create a free account at betteruptime.com.
Add a new HTTPS monitor pointing to https://<your-domain>/health.
Set the check interval to 30 seconds and the confirmation period to 1 check.
Add an alert recipient (on-call email or Slack).
(Optional) Set the expected HTTP status to 200 and add a keyword check for "ok":true.

Better Uptime is also listed as a supported integration in docs/betterstack.mdx.

Alternative: cURL / custom monitor

Any uptime tool that supports HTTP polling can monitor /health:

# Returns 0 on healthy, 1 on unhealthy
curl -sf https://<your-domain>/health | python3 -c "import sys,json; d=json.load(sys.stdin); sys.exit(0 if d['ok'] else 1)"

Common alternatives: UptimeRobot, Checkly, Grafana Synthetic Monitoring, AWS CloudWatch Synthetics.

Interpreting the response

`db`	`redis`	`ok`	Action
`true`	`true`	`true`	All good.
`false`	`true`	`false`	Check `DATABASE_URI` and Postgres service.
`true`	`false`	`false`	Check `REDIS_URI` and Redis service.
`null`	`null`	`true`	Running without DB/Redis (local dev mode).

Overview

First steps

DEVELOPMENT

Development guide

Clone and install

Quality gates (same as CI)

Interactive shell: REPL watchdog demo

VS Code dev container

Benchmark

Deployment

Hosted runtime

Railway (self-hosted alternative)

Remote hosted ops (Railway)

Telemetry and privacy

Kill-switch matrix

Sentry DSN

Deployment tagging

Local PostHog event log

Uptime monitoring

Better Uptime (recommended)

Alternative: cURL / custom monitor

Interpreting the response

​Development guide

​Clone and install

​Quality gates (same as CI)

​Interactive shell: REPL watchdog demo

​VS Code dev container

​Benchmark

​Deployment

​Hosted runtime

​Railway (self-hosted alternative)

​Remote hosted ops (Railway)

​Telemetry and privacy

​Kill-switch matrix

​Sentry DSN

​Deployment tagging

​Local PostHog event log

​Uptime monitoring

​Better Uptime (recommended)

​Alternative: cURL / custom monitor

​Interpreting the response

Development guide

Clone and install

Quality gates (same as CI)

Interactive shell: REPL watchdog demo

VS Code dev container

Benchmark

Deployment

Hosted runtime

Railway (self-hosted alternative)

Remote hosted ops (Railway)

Telemetry and privacy

Kill-switch matrix

Sentry DSN

Deployment tagging

Local PostHog event log

Uptime monitoring

Better Uptime (recommended)

Alternative: cURL / custom monitor

Interpreting the response