Running Frags Locally

Frags is the open-source runtime that powers Diaphora plans. You can run it entirely on your own machine through the CLI to prototype and test plans 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):

#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, TOP_P, and THINKING_LEVEL control generation; 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

Global flags

Configuration files

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

tools.json

tools.json is where you configure every connection your plans can reach. Plans reference these by name, so the same plan can run locally or in a hosted Diaphora service against differently-scoped credentials without changing the plan 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 plan 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 plans run cleanly on your own machine, you can promote them to a hosted Diaphora service:

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