Foral — the runner

Charters for software without public APIs. Foral turns the systems your team already logs into into typed, governed capabilities for your AI agents — served over MCP, with no public API required, no browser puppeteering, and no generated code that rots.

This package is the runner: the commodity client that runs on your infrastructure. It loads a contract, serves its read capabilities to your agent as MCP tools, and keeps writes human-approved. The discovery engine that proposes a contract is not in here — the runner is small and auditable on purpose.

• Website: https://foral.dev
• Docs: https://foral.dev/docs
• Contact: founders@foral.dev

Install

# base — serve / verify / update (no browser)
pipx install foral            # or: npm i -g @foral/cli

# to also sign in locally (foral login), add the browser extra, once:
pipx install 'foral[login]'
playwright install chromium

Quickstart

# 1) the three things the runner needs — it is fail-closed and never guesses
export FORAL_TENANT=your-org                       # isolates your sessions & contracts
export SESSION_ENCRYPTION_KEY="$(foral keygen)"    # encrypts the saved session — keep it safe
export CONTRATOS_DIR=~/foral/contracts             # where your contract YAML lives

# put the contract you downloaded from the sandbox here, named after the system:
#   ~/foral/contracts/acme.yaml   →   foral serve acme   (lowercase)

# 2) sign in once (opens your system's login in a browser; the session stays on this
#    machine, ~30 days) and serve it as an MCP server
foral login acme
foral serve acme

Point your agent at it

# Claude Code
claude mcp add foral -- foral serve acme

// Cursor — ~/.cursor/mcp.json
{ "mcpServers": { "foral": { "command": "foral", "args": ["serve", "acme"] } } }

# Codex — ~/.codex/config.toml
[mcp_servers.foral]
command = "foral"
args = ["serve", "acme"]

Any MCP client works — your own app connects to the same server and calls the system's capabilities as typed tools.

Commands

How it behaves

• Reads run with no browser. Read capabilities call the system's own internal API using your saved session and return typed rows — in milliseconds, no Chromium.
• Writes stay human-approved. Write capabilities are never served as MCP tools and never execute here: the runner returns the declared confirmation phrase instead. Approval happens in your app's harness, never silently.
• The session never leaves your machine. foral login saves an encrypted session locally; it is never sent to Foral. Your password is typed into your own system's form.
• Contracts stay alive. Every read carries a fingerprint of the system's shape. When the system changes, the next read raises an alarm before wrong data can flow — your cue to run foral update.
• Fail-closed by default. An invalid contract does not load; a missing tenant is refused; a missing key is refused. Errors are explicit, never a silent, wrong success.

Environment

Development

pip install -e '.[test]'
pytest

License

Apache-2.0 — see LICENSE.