# 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](https://github.com/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](/content/docs/guides/frags-runtime-locally#configure-your-ai-engine/index.html)):

- **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](https://ollama.com/) 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](https://github.com/FragsHQ/frags/releases?q=cli&expanded=true) page and download the latest CLI binary for your platform. You can also browse [all Frags releases](https://github.com/FragsHQ/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:

```bash
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:

```bash
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](/content/docs/guides/frags-runtime-locally#configure-your-ai-engine/index.html). |
| `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](/content/docs/guides/frags-runtime-locally#tokenjson/index.html).
- **`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.

```json
{
  "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.

```json
{
  "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](/content/docs/api/index.html) to run and stream blueprints over HTTP.
- Call blueprints from your app with the [Python or TypeScript SDK](/content/docs/sdk/index.html).

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