Synapsor Runner

Open-ended investigations. Bounded actions.

Let customer-facing agents answer questions you did not prebuild without crossing tenant boundaries.

The model chooses the question. Runner enforces the authority.

Start With Your Database

The CLI is the preferred live-data interface. Workbench remains preview.

Use a SELECT-only, non-owner development or staging credential:

npx -y @synapsor/runner start --cli

Later examples assume a global install; otherwise prefix them with npx -y @synapsor/runner:

npm install --global @synapsor/runner

Paste the URL into the hidden prompt or export DATABASE_URL. Runner inspects schema metadata, not source rows, then proposes conservative read access that grants nothing until review and activation.

With DATABASE_URL, use the CLI:

synapsor-runner start --cli --from-env DATABASE_URL

Review the starting boundary, then press Enter to activate it. Use M for OpenAI, Anthropic, or a loopback model, and E to edit access. Runner asks before reviewed visible data leaves the machine. Changes remain disabled until human confirmation.

See Database To First Safe Tool.

Prove The Boundary Without A Database

Run with no database, Docker, account, API key, MCP client, model, or global install:

npx -y @synapsor/runner try --prove --no-open

Type APPROVE or REJECT at the trusted terminal prompt. Runner uses a deterministic simulated agent; output includes this abridged, verbatim sequence:

Actor:
  deterministic simulated agent (no LLM call)
Model-facing tools:
  billing.inspect_invoice
  billing.propose_late_fee_waiver
  No execute_sql, approve, apply, or commit tool
Proposed effect:
  late_fee_cents: 5500 -> 0
Source changed:
  No

Guarded commit complete.
Receipt status: applied
Rows affected: 1

Extended proof:
  restart-safe retry: yes
  changed-intent operation reuse rejected: yes
  stale apply refused: yes

The simulated agent can inspect reviewed evidence and form an exact proposal, but cannot approve or commit it. Runner waits for an outside-model decision, rechecks the effect, and records a receipt.

Temporary state stays under ./.synapsor/try/. demo --quick remains a noninteractive compatibility alias.

What Runner Controls

Synapsor Runner is an open-source database-authority layer for Postgres/MySQL. Keep RLS, views, and database permissions underneath it. You review what agents may ask, combine, reveal, and propose; scope, limits, activation, approval, and commit stay outside model-facing tools.

Raw database MCP   Agent -> execute_sql --------------------------> Database
Synapsor Explore   Agent -> app.describe_data / app.explore_data
                            -> reviewed boundary -----------------> Database
Synapsor writes    Agent -> exact proposal -> outside-model decision
                            -> trusted guarded commit ------------> Receipt

The authority path is Explore -> Protect -> Propose -> outside-model decision -> Commit -> Receipt, without falling back to execute_sql.

Read Database Authority And Application Guardrails, or start with safe Postgres MCP, prevent arbitrary LLM SQL, or human approval for agent writes.

Ask A Useful Question

After review, use the preferred terminal Ask, the preview Workbench, or an MCP client. All call the same validation and execution path. Supply an OpenAI or Anthropic key, or use a loopback OpenAI-compatible model. Keys and conversation history stay in memory; loopback traffic stays local.

synapsor-runner try ask --provider openai --model gpt-5-mini

Runner can also configure an MCP client without putting database credentials in its project file:

synapsor-runner mcp install \
  <cursor|claude-code|claude-desktop|vscode|generic-stdio> \
  --project --authoring --project-root . --yes

See Client Recipes for supported MCP hosts.

Local development/staging Explore exposes only:

app.describe_data
app.explore_data

Replay a fixed plan with synapsor-runner explore playground, or open its highlighted editor with synapsor-runner explore workbench --project-root .. explore validate compiles placeholder-only SQL without querying rows or spending budget; explore run preserves enforcement and audit. See Explore Plan Playground.

Agents receive reviewed operations, never SQL. Plans may combine totals, distinct counts, dimensions, filters, comparisons, time windows, rankings, and many-to-one relationships. Every plan is scope-injected, read-only, budget-bounded, and small-cohort suppressed.

Question
Which reviewed regions contributed most to failed payments last week?

Runner-verified result
region       failed_payments
west         184
north        121

1 additional group and its label were withheld below the reviewed cohort minimum.

When a question crosses the boundary, refusal is the result:

REFUSED
The requested customer relationship is proven by the schema but has not been reviewed.
No source query executed.

The model cannot activate the offered review path. Normal answers keep model interpretation separate from Runner-rendered facts; /details shows the exact typed request, validated plan, runtime checks, suppression, and evidence.

Explore is local by default. Production opt-in over secured Streamable HTTP requires verified JWT scope, per-principal and tenant budgets, rate limits, and atomic shared-Postgres accounting. See Production Scoped Explore Over HTTP and Explore And Protect.

Turn A Useful Question Into Production Access

After an answer proves useful, run /protect. Runner freezes that one successful analysis into a named read-only capability with generated DSL, canonical JSON, tests, and provenance. It starts disabled.

CLI and Workbench use the same review and separate human activation. The CLI needs no browser or copied digest; changed artifacts fail closed. Models cannot invoke Protect or activation.

/details A2 --sql can show an operator-only parameterized statement with all values redacted. SQL never reaches the model, MCP response, or durable evidence.

For fixed production question shapes, switch the selected project client from temporary Explore to the activated named capability:

CLIENT=claude-code # or cursor / vscode
synapsor-runner mcp install "$CLIENT" --project \
  --config ./synapsor.runner.json \
  --store ./.synapsor/local.db \
  --yes

Protected capabilities remain the narrowest production choice. For reviewed ad-hoc analytics, synapsor-runner config init --production-explore generates secured runtime config from the boundary without secrets.

Let Agents Propose Bounded Changes

For writes, describe one business action. Runner generates an inert TypeScript draft; it does not silently add a tool or change active authority:

synapsor-runner start \
  --action plan_credit \
  --description "Propose one reviewed customer plan credit" \
  --based-on support.inspect_customer

After a human reviews and activates that action, the agent can create an exact proposal, sometimes called a Data PR. It still cannot approve or apply it:

Proposal  support.propose_plan_credit on CUS-3001
Effect    plan_credit_cents: 0 -> 2500
Database  unchanged until an outside-model decision

Teams may review a policy once so routine requests within fixed value, rate, and scope limits are policy-approved. Automatic application still requires a separate deployment opt-in and a trusted worker that repeats every guard.

Auto-approval does not mean auto-apply: the exact contract digest and deployment both opt into supervised execution. External notifications are disabled and quiet by default. A webhook response cannot approve or apply.

Immediately before a Runner-managed commit, live scope, evidence freshness, version, bounds, limits, and idempotency are rechecked. Drift causes no mutation. See Supervised Apply, Proposal Freshness, and Verified Operator Identity.

Other Paths

Audit An Existing MCP Server

Already have database MCP tools? Inspect a manifest, remote tools/list, or stdio server without invoking its business tools:

npx -y @synapsor/runner audit --example dangerous-db-mcp
synapsor-runner audit ./tools-list.json

The audit flags raw SQL, arbitrary identifiers, model-controlled authority, and model-facing write execution. See MCP Audit.

Keep Your Existing Service Layer

If your application already exposes narrow authenticated business operations, keep them. Runner can add the agent-specific review, proposal, policy, approval, evidence, receipt, and replay lifecycle around those operations. Multi-step transactions and external effects remain in an application-owned executor. See Application Guardrails.

Why Not Raw Text-To-SQL?

Text-to-SQL can produce confident, plausible, wrong answers while holding much more authority than the question requires. A published ReFoRCE pipeline reports about 11% execution accuracy on the enterprise-scale BEAVER benchmark. In EntSQL, 54.6% of 982 observed failures were wrong filters.

These benchmark-specific figures are not a Runner accuracy claim. Runner cannot decide what a business term means. It removes arbitrary SQL authority, limits the legal plan space, injects trusted scope, and records what was actually validated and executed.

Safety Model

Reviewed capabilities fix context, fields, relationships, operations, bounds, and approval rules. Model-facing tools may inspect bounded data or create exact proposals, but they cannot activate access, choose tenant/principal scope, approve, apply, or revert. Runner does not make a raw-SQL client safe.

Choose application scope, PostgreSQL RLS, or tenant-bound credentials for your threat model; Runner does not replace database permissions. Stdio opens no socket. Network MCP requires authenticated encrypted transport and verified session context. See Threat Model, Database Scope, and HTTP MCP.

You May Not Need Runner

Read-only views or fixed low-risk operations may suffice when questions and actions are known in advance. Runner is for open-ended investigations inside a reviewed boundary, bounded writes, and shared evidence, approvals, retries, conflicts, receipts, and replay.

Trust And Verification

Start with the Security Boundary. Live gates cover scope, mutation, freshness, suppression, and replay. Runner does not replace database or application authorization. Supported sources are PostgreSQL 13-18, full-grammar MySQL 8.0.16+, and limited-tier MySQL 8.0.11-8.0.15 or 5.7. Unsupported grammar is hidden before model discovery. See Database Server Compatibility.

Runner uses SQLite or a Postgres ledger. Synapsor Cloud adds registry, approval, jobs, and redacted activity; credentials and execution stay local. Browse Capability Authoring, OSS vs Cloud, or the documentation index.

License

Synapsor Runner is open source under the Apache License 2.0 (Apache-2.0). See Licensing and Trademarks. Synapsor Cloud and proprietary Synapsor platform components are outside this repository.

Contributor workflows live in CONTRIBUTING.md.