Coral: Local-First SQL Runtime for Agents

Coral is redefining how agents access data by providing a local-first SQL runtime that sits between your agents and a constellation of data sources—APIs, files, and services. It lets you query multiple live sources with a single SQL interface, inspect schemas and tables, or expose the same runtime over MCP so agents can use it without bespoke glue code. The result is a unified, auditable, and scalable data access layer designed for modern AI workflows.

[Coral is built to power thoughtful, data-aware agents.] You can ask your agents complex questions about your data:

Or run SQL queries yourself:

Introduction: What Coral Enables

Coral changes the game for AI-driven workflows by eliminating the friction that typically slows data-driven agent work. Instead of issuing a cascade of per-tool calls, re-authenticating across services, or stitching results together by hand, Coral offers one query surface that respects the realities of multi-source data environments. The core idea is simple, yet powerful: represent every data source as a SQL surface, then let the agent execute a single SQL query that spans those surfaces.

Key benefits at a glance include:

• A single, consistent query interface across many sources
• Built-in support for pagination, efficient data transfer, and selective column retrieval
• Local-first authentication and credential handling that stays on your machine
• Simple extension points to add new data sources and unlock cross-source reasoning

Why Coral Matters: The Pain Points Coral Addresses

Modern agent workflows often live in a world of countless small tools. Each tool represents a different API, a different authentication method, and a different data model. While this approach can be effective in isolated tasks, it creates a handful of enduring problems when agents attempt cross-source reasoning:

• Too many tool calls: Each step across tools multiplies API calls, increasing latency and cost.
• Repeated auth, pagination, and retry logic: Each source becomes a bespoke integration, with its own error handling and rules.
• Poor cross-source reasoning: Joining data across APIs is tedious, verbose, and brittle.
• High token traffic: Transmitting large, nested API responses or aggregate results taxes token budgets.
• Brittle glue code and prompts: Custom hand-rolled glue scripts become fragile and hard to maintain.

Coral’s answer is a unified, SQL-based interface that abstracts away those differences. Instead of orchestrating multiple tools, you write a SQL query that pulls data from many sources as if they were tables in a single database. The engine handles translation to API calls or file reads, manages pagination, and returns a clean, tabular result set.

How Coral Works: Architecture and Data Flow

At its core, Coral is a bridging layer that sits between agents and data sources. The agent emits a SQL query. Coral translates that query into the appropriate API calls or file reads, then reconstructs the results into a single, cohesive table that the agent can consume. The flow looks like this:

• Agent issues a SQL query through Coral
• Coral analyzes the query and dispatches requests to installed sources (APIs, files, etc.)
• Each source is represented by a source spec (a YAML descriptor) that declares how to reach the API or dataset and which tables and columns are exposed
• Coral fetches, combines, and returns a single result set with the requested columns and rows
• For complex cross-source queries, joins are executed locally after retrieving data from each side

The concept of “sources” is central. Each source is described by a source spec, which is a YAML definition plus the credentials and variables the user configured. When you run a command like coral source add github, Coral installs the github source and exposes it in the SQL namespace as the github schema, so tables such as github.issues and github.pulls become queryable.

• A source spec defines how to reach an API or local dataset
• Credentials and variables are stored securely on your machine and only used at query time
• Federation across sources is achieved by exposing them as SQL tables; joins across sources can then be written as a single SQL statement

A simple cross-source example demonstrates the power of the approach. You can, for instance, join Linear issues with GitHub pulls to see which Linear issues are associated with open GitHub PRs. The pattern is natural and leverages the SQL engine’s join semantics to fuse results on the fly, without requiring you to stitch data together in an external pipeline.

Code examples you’ll likely use

• Cross-source join example: SELECT a.issueidentifier, a.url, p.state FROM linear.attachments a JOIN github.pulls p ON p.htmlurl = a.url WHERE p.owner = 'withcoral' AND p.repo = 'coral'

• Source authentication and credentials: Coral reads environment variables for credentials when you run coral source add, or it can prompt you in interactive mode to gather the necessary secrets. These credentials stay on your machine and are used only during query execution.

• Built for production: read-focused design Coral’s read-first approach is tuned for performance. It paginates where necessary, returns rows in a stable tabular format, and minimizes API traffic through query pushdown and caching. This makes complex analyses across many sources feasible without exploding per-source API calls.

A deeper dive into the architecture is available on the project’s architecture page, but the gist is that Coral abstracts away the heterogeneity of data sources behind a consistent SQL interface while maintaining a secure, local-first stance.

Bundled Sources: A Rich Suite by Default

Coral ships with a broad set of bundled sources to get you started quickly. The bundled set often includes:

• Datadog
• GitHub
• Linear
• Sentry
• Stripe
• Other popular services
• Local JSONL and Parquet files for local data

If you want to see what’s included in your current build, you can run coral source discover. If your favorite data source isn’t among the bundled options, you can still reach it by writing a custom source, or you can request support for additional sources via the project’s issue tracker.

Getting Started: A Quickstart Guide

For newcomers, Coral offers a path from install to your first SQL query in a few clear steps. A quickstart outline:

1) Install Coral

• macOS: brew install withcoral/tap/coral
• Linux: curl -fsSL https://withcoral.com/install.sh | sh
• Windows: Download coral.exe from the latest GitHub release and place it on your PATH

2) Discover bundled sources

• coral source discover

3) Add a source

• coral source add --interactive github
• In interactive mode, Coral prompts for required variables or secrets. For scripted setups, export the environment variables (for example, GITHUB_TOKEN) and run coral source add github.

4) Query your data

• coral.tables and coral.table_functions reveal what’s available
• Example: List issues from GitHub for your account coral sql "SELECT number, title, state, createdat FROM github.issues WHERE owner = 'withcoral' AND repo = 'coral' AND state = 'open' ORDER BY createdat DESC LIMIT 10"

Images provide a visual sense of the Coral workflow and demonstration queries:

• A visual snippet of a Claude-driven SQL query demonstrating Coral [coral sql query demo] (sql-query-readme.gif is a good companion here)

Use Coral with an Agent: MCP and Beyond

Coral ships with an MCP server that presents Coral to agents as a read-only SQL database. Once you’ve added at least one source, you can connect it to popular agents and tools:

• Claude Code or Claude with MCP: claude mcp add --scope user coral -- coral mcp-stdio
• Codex-enabled environments (VS Code, Cursor, etc.)

In practice, this means your agent can query sources directly, bypassing bespoke glue code, and still maintain a discoverable, auditable pipeline. Coral also publishes a suite of skills designed to teach your agent a discovery-first SQL workflow. The skills include functions like listcatalog, coral.tables, coral.tablefunctions, coral.columns, and more.

• Install skills: npx skills add withcoral/skills
• Once installed, your agent can list available tables and surface the SQL-based catalog in a natural way, using the same surface you’d use for a standalone SQL environment.

Local State and Configuration: Where Coral Keeps Its Levers

Coral stores state in a platform-specific configuration directory on your machine. You can influence this directory with an environment variable to keep configuration separated from your project:

• export CORALCONFIGDIR=/path/to/coral-config

Important files and what they do:

• config.toml: Holds installed-source metadata and non-secret variables
• workspaces//sources//manifest.yaml: Contains imported source specs
• Secrets: Stored separately within the same local trust boundary

Bundled source specs are not copied into the config directory. Coral resolves them from the current binary when validating or querying a bundled source, so upgrades can pick up newer manifests without re-adding sources.

Development and Testing: Keeping Coral Healthy

If you’re a contributor or maintainer, a few practical steps keep Coral in good shape:

• Install the local test runner:
• macOS: brew install cargo-nextest
• Or via Cargo: cargo install cargo-nextest --locked
• Run the internal checks: make rust-checks

Documentation and Community: Where to Learn More and Get Help

For setup guides, reference materials, and examples, the official Coral docs are the best place to start:

• https://withcoral.com/docs

If you have questions, ideas, or wish to show off a pipeline you built, the Coral community vibes live in:

• Discord: https://withcoral.com/discord
• GitHub issues: https://github.com/withcoral/coral/issues

Contributing: How to Help

Coral welcomes contributions across the spectrum:

• Bug fixes
• Tests
• Documentation improvements
• Source improvements
• Usability enhancements

Before opening a pull request, it’s a good practice to review the contribution guidelines:

• CONtributing.md

Security: Responsible Disclosure

Coral asks that security issues be reported privately. See the SECURITY.md for details.

Licensing

Coral is released under the Apache License 2.0. See the LICENSE file for terms and conditions.

A Richer Picture: What Coral Enables for Teams

The thrust of Coral’s approach is not merely a different data access technique; it’s a shift in how teams collaborate around data. By giving agents a single, auditable SQL surface over a diverse fabric of sources, Coral unlocks cross-functional workflows that previously required bespoke glue code and brittle orchestration.

• Cross-source reasoning becomes natural: You can write one SQL query to join customer data from a CRM with billing data from Stripe, or combine logs from Datadog with issue histories from GitHub.
• Read-first performance characteristics: For read-heavy analysis, Coral’s pagination and query pushdown keep latency in line with expectations for interactive AI workflows.
• Local-first security and governance: Credentials stay on the user’s machine and never leave the host, reducing risk and simplifying compliance in many scenarios.
• Extensibility at the edge: If a necessary data source isn’t bundled, it is straightforward to create a custom source. Coral’s design makes this approachable for teams that want to adapt the runtime to their unique data landscapes.
• Developer-friendly exploration: The ability to inspect schemas and table catalogs from Coral itself makes it easy to understand what’s available and how best to structure queries.

Visuals and Demos

To give you a sense of Coral in action, the project provides visual demonstrations that highlight typical usage patterns:

• A Claude-driven SQL demo illustrates how natural-language prompts can drive complex queries, which Coral then translates into a single SQL statement against multiple sources.
• A join demonstration shows how a single SQL statement can fuse data from Linear and GitHub, resulting in a coherent view of cross-source activity.
• A README-like animation demonstrates the SQL surface and the process by which Coral returns a unified result set.

What to Try Next

• Install Coral on your system and explore the bundled sources.
• Add your own data sources using coral source add and start crafting cross-source queries.
• Connect Coral to your preferred agent via MCP and begin instructing your agent with SQL-powered capabilities.
• Experiment with the sample cross-source queries to see how Coral handles joins and data shape across APIs and files.
• If you need more, consider creating a custom source spec for your own API or dataset to see how Coral expands to your data ecosystem.

Closing Thoughts

Coral represents a pragmatic resolution to the fragmentation that often plagues data-driven AI workflows. By offering a local-first, SQL-based runtime that can natively join across APIs, files, and other sources, Coral empowers agents to reason more deeply, cheaply, and transparently. It’s designed to be used out of the box with a minimal friction path to production-ready queries, while also providing robust extension points for teams that need deeper customization.

If you’re curious to see Coral in action, start with the quickstart steps, attach your preferred sources, and begin querying. The ability to pull data from multiple sources as if they were one coherent database is not just a nicety—it’s a practical capability that changes how you think about data access for AI agents.

Images above demonstrate the practical aspects of Coral:

• The cover image marks the gateway into a multi-source world
• The Claude-driven and GIF-based demonstrations illustrate the end-to-end flow from SQL to API calls and back to a unified result
• The SQL readme image offers a tangible look at query construction and results

As you experiment, you’ll likely discover new ways to use Coral to simplify cross-source analyses, reduce token and latency costs, and provide your agents with a more reliable, auditable, and scalable data access layer. Coral is designed to be developer-friendly, production-ready, and ready to grow with your data ecosystem as it evolves.