Current state
walked through the OpenSRE quickstart on a fresh Ubuntu 22.04 box (glibc 2.35, no sudo) as if i'd just landed on the docs. three friction points came up that all share the same root cause: the path that actually works for a new external user is hidden behind paths that don't.
1. opensre onboard local_llm is not in the quickstart
the curl one-liner installer is the documented happy path. on ubuntu 22.04 it dies on libpython3.13.so.1.0: GLIBC_2.38 not found (separate fix in flight, see #1284 / #1408). pivoted to source via git clone && uv sync --frozen --extra dev && uv run opensre --version, which worked in ~90 seconds.
then ran uv run opensre onboard. wizard prompted for ANTHROPIC_API_KEY. for someone evaluating "is this product worth signing up to anthropic for", being asked for the api key before seeing anything run is the wrong order.
discovered uv run opensre onboard local_llm only by reading onboard --help. its description: "Zero-config local LLM setup via Ollama. No API key required." that is exactly the "try before signup" path the quickstart should be promoting, and it is invisible. not in docs/quickstart.mdx, not in README.md quickstart section, not in any top-level onboarding tab.
2. source-install fallback isn't in the quickstart
SETUP.md documents git clone && uv sync && uv run opensre cleanly, but it reads as "development environment setup" not "binary failed? try this." for the duration that the curl installer is gated on glibc 2.38, source is the only way ubuntu 22.04 / older RHEL users can evaluate the product. a 3-line fallback under the install tabs in docs/quickstart.mdx would unblock most of that audience.
3. error UX is inconsistent between missing-key and provider-unreachable
uv run opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json with no LLM_PROVIDER produces a clean 2-line Rich error box: "ANTHROPIC_API_KEY to be set. Run opensre onboard." nice.
same command with LLM_PROVIDER=ollama and no ollama daemon running produces a 50-line httpx/httpcore/openai traceback, with the useful sentence RuntimeError: Cannot connect to Ollama API on the last line. same product, two error voices, one of them feels like a bug rather than a config issue.
these three points come from a single fresh-user walkthrough. one filing, three small fixes, listed below.
Desired state
Fix 1: promote opensre onboard local_llm to step 1 of the quickstart
docs/quickstart.mdx gets a new "Onboard" step with two tabs:
- Local LLM (no API key) —
opensre onboard local_llm (recommended for evaluation)
- Anthropic / OpenAI / Bedrock —
opensre onboard
README.md quickstart section mirrors the same tab order. ~10-line docs change.
Fix 2: source-install fallback in docs/quickstart.mdx
three-line block under the install tabs:
If the binary install fails (e.g. glibc < 2.38 on Ubuntu 22.04 or older), you can run from source via uv:
git clone https://github.com/Tracer-Cloud/opensre && cd opensre && uv sync --frozen --extra dev && uv run opensre --version
links forward to SETUP.md for full dev setup. ~5-line docs change. closes once the glibc release rebuild lands but useful in the interim.
Fix 3: wrap provider connectivity errors in the same Rich error box as missing-key
one try/except at the investigate entry-point catches the RuntimeError raised by app/services/llm_client.py when a provider can't be reached, re-raises through the same Rich-formatted error path that already handles missing keys. ~15-line code change plus one unit test on the LLM_PROVIDER=ollama + no-daemon path.
ship plan
if the team is on board, happy to ship these as three small PRs:
- docs PR — local_llm promotion (Fix 1)
- docs PR — source-install fallback (Fix 3)
- code PR — provider-unreachable Rich error wrap (Fix 3)
splitting docs from code so the docs land fast and the code PR can carry the test + greptile pass without blocking the easy wins. happy to defer to whatever ordering the team prefers, or to drop any of the three if scope feels off.
would love a maintainer signal on which (if any) of the three the team wants before opening PRs. labelling or a one-line "yes ship that" comment is enough.
Current state
walked through the OpenSRE quickstart on a fresh Ubuntu 22.04 box (glibc 2.35, no sudo) as if i'd just landed on the docs. three friction points came up that all share the same root cause: the path that actually works for a new external user is hidden behind paths that don't.
1.
opensre onboard local_llmis not in the quickstartthe curl one-liner installer is the documented happy path. on ubuntu 22.04 it dies on
libpython3.13.so.1.0: GLIBC_2.38 not found(separate fix in flight, see #1284 / #1408). pivoted to source viagit clone && uv sync --frozen --extra dev && uv run opensre --version, which worked in ~90 seconds.then ran
uv run opensre onboard. wizard prompted forANTHROPIC_API_KEY. for someone evaluating "is this product worth signing up to anthropic for", being asked for the api key before seeing anything run is the wrong order.discovered
uv run opensre onboard local_llmonly by readingonboard --help. its description: "Zero-config local LLM setup via Ollama. No API key required." that is exactly the "try before signup" path the quickstart should be promoting, and it is invisible. not indocs/quickstart.mdx, not inREADME.mdquickstart section, not in any top-level onboarding tab.2. source-install fallback isn't in the quickstart
SETUP.mddocumentsgit clone && uv sync && uv run opensrecleanly, but it reads as "development environment setup" not "binary failed? try this." for the duration that the curl installer is gated on glibc 2.38, source is the only way ubuntu 22.04 / older RHEL users can evaluate the product. a 3-line fallback under the install tabs indocs/quickstart.mdxwould unblock most of that audience.3. error UX is inconsistent between missing-key and provider-unreachable
uv run opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.jsonwith noLLM_PROVIDERproduces a clean 2-line Rich error box: "ANTHROPIC_API_KEY to be set. Runopensre onboard." nice.same command with
LLM_PROVIDER=ollamaand no ollama daemon running produces a 50-line httpx/httpcore/openai traceback, with the useful sentenceRuntimeError: Cannot connect to Ollama APIon the last line. same product, two error voices, one of them feels like a bug rather than a config issue.these three points come from a single fresh-user walkthrough. one filing, three small fixes, listed below.
Desired state
Fix 1: promote
opensre onboard local_llmto step 1 of the quickstartdocs/quickstart.mdxgets a new "Onboard" step with two tabs:opensre onboard local_llm(recommended for evaluation)opensre onboardREADME.mdquickstart section mirrors the same tab order. ~10-line docs change.Fix 2: source-install fallback in
docs/quickstart.mdxthree-line block under the install tabs:
links forward to
SETUP.mdfor full dev setup. ~5-line docs change. closes once the glibc release rebuild lands but useful in the interim.Fix 3: wrap provider connectivity errors in the same Rich error box as missing-key
one try/except at the
investigateentry-point catches theRuntimeErrorraised byapp/services/llm_client.pywhen a provider can't be reached, re-raises through the same Rich-formatted error path that already handles missing keys. ~15-line code change plus one unit test on theLLM_PROVIDER=ollama+ no-daemon path.ship plan
if the team is on board, happy to ship these as three small PRs:
splitting docs from code so the docs land fast and the code PR can carry the test + greptile pass without blocking the easy wins. happy to defer to whatever ordering the team prefers, or to drop any of the three if scope feels off.
would love a maintainer signal on which (if any) of the three the team wants before opening PRs. labelling or a one-line "yes ship that" comment is enough.