Cora

AI Agent-Ready Local-First Dashboards.

Cora is a file-driven dashboard runtime: dashboard.json is rendered live, while cora.config.yaml defines source bindings and refresh behavior.

The development workflow uses Bun, while the published CLI runs as Node-compatible JavaScript.

Quick start

# install all workspace dependencies (CLI + UI + internal packages)
bun install
bun run src/cli.ts init --template saas
bun run src/cli.ts serve

Open http://127.0.0.1:4242.

Global install target:

npm install -g @fumi-ops/cora

Workspace files

• dashboard.json: rendered dashboard values (agent-writable)
• cora.config.yaml: source and widget binding config
• cora.cache.json: auto-managed source cache state
• .env: optional project credentials
• CORA_AGENT_INSTRUCTIONS.md: generated agent contract

Commands

cora init [--template <name>] [--list-templates] [--force]
cora serve [--port <n>] [--no-open] [--no-fetch] [--file <path>] [--config <path>]
cora fetch [--source <id>] [--file <path>] [--config <path>]
cora validate [--file <path>] [--config <path>]
cora export [--file <path>] [--out <path>]
cora sources list [--config <path>]
cora config set <key> [--value <secret>]
cora config get <key>
cora config unset <key>

Template names:

• starter
• saas
• ecommerce
• freelancer
• developer

Connector support

Built-in connectors:

• postgres
• mysql
• sqlite
• duckdb
• http
• stripe
• plausible
• github

Named query examples:

• Stripe: mrr, arr, new_customers_today, revenue_mtd, churn_rate, active_subscriptions
• Plausible: visitors_today, visitors_mtd, top_pages, bounce_rate
• GitHub: stars, open_issues, open_prs, commits_today

Credential values are resolved in this order:

1. Shell environment variable
2. Project .env
3. Encrypted store ~/.cora/store.enc

Community connectors

Cora auto-discovers connector packages from local node_modules with the prefix cora-connector-* (including scoped packages like @acme/cora-connector-foo).

If a source uses type: foo, install a package that exports connector foo and Cora will load it at runtime.

Agent write endpoint

Agents can patch a single widget without direct file access:

POST http://127.0.0.1:4242/api/widget
Content-Type: application/json

{ "id": "mrr", "value": 4800, "trend": "+14%" }

Requirements

• Node.js >=22.13.0

UI stack

• React 19
• Basecoat CSS
• Chart.js
• Tailwind CSS
• SSE from the local dashboard server

Develop or build the UI bundle from the root workspace:

bun run dev:ui
bun run build:ui
bun run check:embedded-ui

Validation commands:

bun run typecheck
bun run lint
bun run test
bun run ci

Security model

• Connector calls run in the local CLI process only.
• Browser never receives credential values.
• Server binds to 127.0.0.1.
• Credentials stored with AES-256-GCM in ~/.cora/store.enc.
• Secret material is local-only (~/.cora/master.key) with restricted file permissions.

Contributing

See CONTRIBUTING.md for local development setup, test commands, and pull request expectations.

Security disclosures

See SECURITY.md to report vulnerabilities privately.

Code of conduct

This project follows the Contributor Covenant.

License

MIT