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.
