Running Frags Locally | Diaphora Docs | Diaphora

Running Frags Locally

Frags is the open-source runtime that powers Diaphora blueprints. You can run it entirely on your own machine through the CLI to prototype and test blueprints before promoting them to a hosted Diaphora service.

This guide takes you from zero to your first local run. Frags is open source; the runtime and its documentation live in the FragsHQ/frags repository.

Before you start

You'll need an AI engine for Frags to talk to. Frags supports several, and you can swap between them at any time (see Configure your AI engine):

Gemini — Google Gemini via Vertex; requires a Google Cloud account and a Vertex-enabled service account key.
ChatGPT — OpenAI, or any OpenAI-compatible endpoint; requires an API key and base URL.
Anthropic — Anthropic Claude; requires an API key.
Ollama — runs models locally; install Ollama and pull a model such as qwen3:latest.

The CLI

The CLI is the simplest way to experience what Frags can do.

Install the CLI

Head to the CLI releases page and download the latest CLI binary for your platform. You can also browse all Frags releases.
Make the binary executable (on *nix systems):

    chmod +x <file_name>
    ```

- The binaries are not signed and will trigger a security alert on most systems, so you'll need to bypass the security check the first time you run it.
- Run the binary once to generate the configuration file `.env`.
- Configure the `.env` file with your desired settings (see below).

### Configure your AI engine

The main choice is the `AI_ENGINE` setting — the model provider Frags talks to. Supported values:

- `gemini` — Google Gemini via Vertex.
- `chatgpt` — OpenAI, or any OpenAI-compatible endpoint (set `CHATGPT_BASE_URL`).
- `anthropic` — Anthropic Claude.
- `ollama` — models running locally through Ollama.

Then set `MODEL` to a model the active engine supports — for example `gemini-3.5-flash`, `gpt-4o`, or a local `qwen3:latest`.

Because each provider's settings live side by side in `.env`, you can keep several configured at once and **swap models by flipping the `AI_ENGINE` and `MODEL` lines** — nothing else needs to change.

**Note:** if you use **Google Gemini** you'll need a **Google Cloud** account and a **Vertex-enabled service account key**.

A sample `.env` with multiple engines configured (secrets redacted — commented lines are the inactive alternatives):

```bash
#AI_ENGINE=chatgpt
AI_ENGINE=gemini
CHATGPT_API_KEY=sk-proj-...
CHATGPT_BASE_URL=https://api.openai.com/v1
#ANTHROPIC_API_KEY=sk-ant-...
GEMINI_LOCATION=global
GEMINI_PROJECT_ID=your-project-id
GEMINI_SERVICE_ACCOUNT_PATH=./service-account.json
MODEL=gemini-3.5-flash
#MODEL=gemini-2.5-flash
#MODEL=gpt-4o
THINKING_LEVEL=MEDIUM
NUM_PREDICT=1024
OLLAMA_BASE_URL=http://localhost:11434
PARALLEL_WORKERS=1
TEMPERATURE=0.1
TOP_K=40
TOP_P=0.9
USE_K_FORMAT=false

TEMPERATURE, TOP_K, and TOP_P control sampling randomness during generation (lower = more deterministic); THINKING_LEVEL sets reasoning effort on models that support it; NUM_PREDICT caps output tokens; PARALLEL_WORKERS sets how many sessions run concurrently.

Run your first prompt

Let's use the simplest command:

frags ask "What is the meaning of life?"

If you receive an answer, then you're lucky — and your local runtime is working.

CLI commands

Frags is an advanced AI agent for complex data workflows — retrieval, transformation, extraction, and aggregation. Highly customizable and extensible, it prioritizes precision.

Invoke it as frags [command] (or frags [flags]), and pass -h to any command for its own help:

frags [command]
frags [flags]

Available commands

Command	Description
`ask`	Ask a question to the AI, using the current Frags settings and tools.
`run`	Run a Frags blueprint from a YAML or FML file.
`render`	Render a YAML/JSON data file into a document using a template.
`config`	Print the current configuration.
`debug`	Debug-related commands.
`lsp`	Run an LSP server for the FML language.
`web`	Webserver-related commands.
`completion`	Generate the autocompletion script for the specified shell.
`help`	Help about any command.

Global flags

Flag	Description
`-h, --help`	Help for `frags` or any subcommand.
`-v, --version`	Print the version.

Configuration files

The local runtime keeps its configuration in a few files in your working directory:

File	What it holds
`.env`	Engine selection and generation settings — see Configure your AI engine.
`tools.json`	Your connections: MCP servers and built-in collections (filesystem, HTTP, database).
`token.json`	The local token store — Frags holds and refreshes the OAuth tokens for each connected MCP here.

tools.json

tools.json is where you configure every connection your blueprints can reach. Blueprints reference these by name, so the same blueprint can run locally or in a hosted Diaphora service against differently-scoped credentials without changing the blueprint itself.

It has two top-level maps:

mcpServers — one entry per MCP server, each with a url and a disabled flag. Servers that require OAuth also take a client_id and client_secret; once authorized, Frags stores the resulting tokens in token.json.
collections — built-in connectors. fs (filesystem) and http are simple on/off toggles, while postgres takes a params.postgres_url connection string.

Flip a connection's disabled flag to turn it on or off without removing its configuration.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp",
      "disabled": true
    },
    "slack": {
      "url": "https://<tenant>.platform.barndoor.ai/mcp/slack-user",
      "disabled": false,
      "client_id": "<client-id>",
      "client_secret": "<client-secret>"
    },
    "gmail": {
      "url": "https://<tenant>.platform.barndoor.ai/mcp/gmail",
      "disabled": false,
      "client_id": "<client-id>",
      "client_secret": "<client-secret>"
    },
    "notion": {
      "url": "https://<tenant>.platform.barndoor.ai/mcp/notion",
      "disabled": true
    }
  },
  "collections": {
    "fs": {
      "disabled": true
    },
    "postgres": {
      "disabled": false,
      "params": {
        "postgres_url": "postgresql://<user>:<password>@<host>.neon.tech/neondb?sslmode=require&channel_binding=require"
      }
    },
    "http": {
      "disabled": false
    }
  }
}

As with token.json, keep tools.json out of version control when it contains real client secrets or database URLs.

token.json

When a blueprint uses an MCP server that requires OAuth, Frags runs the authorization flow once and stores the resulting credentials in token.json, keyed by a hash of the connection. It refreshes them automatically as they expire, so you rarely need to touch this file by hand.

{
  "items": {
    "1883918e…": {
      "host": "https://<tenant>.platform.barndoor.ai/mcp/google-calendar",
      "client_id": "<oauth-client-id>",
      "access_token": "eyJ0eXAi…redacted",
      "refresh_token": "eyJhbG…redacted",
      "token_type": "Bearer",
      "expiry": "2026-06-02T18:17:15-04:00"
    }
  }
}

Each entry records the MCP host, the client_id Frags authenticated as, the current access_token and refresh_token, the token_type, and the access token's expiry. The items keys are content hashes that identify each connection.

Keep token.json out of version control. It holds live access and refresh tokens — treat it like any other secret, never commit it, and rotate the credentials if it's ever exposed.

Next steps

Once your blueprints run cleanly on your own machine, you can promote them to a hosted Diaphora service:

Use the API reference to run and stream blueprints over HTTP.
Call blueprints from your app with the Python or TypeScript SDK.

Install the open-source Frags CLI, point it at Gemini, ChatGPT, Anthropic, or Ollama, and run your first blueprint on your own machine.