Skip to main content

​
Development guide

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

​
Clone and 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.

​
Local checks and PR validation

Follow CI.md for local validation, required PR checks, and review follow-through.

​
Interactive shell action policy

Action-planner behavior, postprocessing transforms, compatibility seams, and the rule-extension checklist are documented in docs/interactive-shell-action-policy.md.

​
Package architecture

The eight first-party packages, the five-tier layering (which package may import which), the folder diagram, per-layer responsibilities, and cross-layer flows are documented in docs/ARCHITECTURE.md.

​
Tool registry — surface-scoped, lazy loading

Loading every vendor tool at startup was slow. A static index (tools/registry_index.py) reads tool metadata by scanning the source, without importing executors, so a turn loads only the tools it needs.
  • get_registered_tools(surface) imports only that surface’s tool modules.
  • get_tool_descriptors(surface) returns metadata with no executor import.
  • load_tool(descriptor) imports the executor, only when a tool runs.
Adding a vendor tool is a @tool/BaseTool module; the index finds it and no other vendor is imported. tests/tools/test_registry_index.py checks the index matches the imported registry exactly, so they cannot drift.

​
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.

​
Deployment

Full deployment instructions, prerequisites, and environment variable reference: DEPLOYMENT.md Quick reference:

​
Hosted runtime (Railway / ECS / Vercel)

  1. Deploy the repository Dockerfile and select the runtime with MODE (web, gateway, or scheduler). The container installs the current main-channel build on start. Restart it, or run opensre update -y inside it, to pick up a newer build. Rebuild the image when the toolchain (Git, GitHub CLI, Node, Codex) changes.
  2. Set LLM_PROVIDER and the matching API key (for example ANTHROPIC_API_KEY, OPENAI_API_KEY — see .env.example).
  3. Set DATABASE_URL when gateway records must be shared through Postgres (required for Slack Events API unless the single-replica local-dedup escape hatch is enabled).
  4. Use a shared OPENSRE_HOME mount when multiple processes need the same scheduler tasks. If OPENSRE_CONTEXT_ROOT is set, make that root durable and shared for organization-bound sessions too.
  5. Add integration and storage env vars your deployment needs.
Minimal LLM env:
For Railway: add Postgres and set DATABASE_URL only when the gateway needs shared records; Redis is not part of the gateway persistence path. Set OPENSRE_DEPLOYMENT_METHOD=railway for telemetry labeling.

​
Telemetry and privacy

opensre ships with two telemetry stacks, both opt-out:
  • Product analytics — lifecycle and usage events sent through app.opensre.com (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. Product events also carry execution_environment (local, ci, container, or ci_container), is_ci, is_container, and container_runtime. Use these first-party fields to exclude automated environments from product funnels. A random install ID is stored under ~/.opensre/anonymous_id. Telemetry is off in GitHub Actions and pytest.

​
Kill-switch matrix

Full opt-out:

​
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 product event log

By default, outbound product event properties are also appended to ~/.opensre/analytics_events.txt (rotates at 1000 lines). Disable:
Metadata events do not collect alert contents, file contents, hostnames, credentials, or raw CLI arguments. The separately documented $ai_generation event contains redacted prompt and response text.