Getting Started with Fracta

Fracta is a multi-agent orchestration system. It lets you spawn parallel AI agents from Claude Code, Codex, or OpenCode — each working on a separate task — and coordinate their output. You keep using your preferred AI CLI as you normally would; fracta adds the ability to fan work out to multiple agents and bring it back together. This guide covers the core concepts, how credentials flow, and which deployment mode to pick. Each mode has its own quickstart with step-by-step instructions.

Architecture at a Glance

Every deployment mode shares the same thin-client architecture. Your AI runtime talks to fracta serve over stdio; fracta serve forwards requests to the control plane over HTTP. The control plane owns agent lifecycle, and the gateway provides MCP tools to agents.

Your machine                              Server-side (local daemon, container, or pod)
┌───────────────────────┐                ┌──────────────────────────────────────┐
│                       │                │                                      │
│ Claude / Codex /      │                │  Control Plane (:9090)               │
│ OpenCode              │     stdio      │    Agent lifecycle (spawn/kill)      │
│   └─ fracta serve  ────┼────────┐       │    State store (SQLite or Postgres)  │
│                       │        │ HTTP  │    Mission queue + workers           │
│                       │        ├──────>│    Reaper (auto-cleanup)             │
│ fracta spawn (CLI)  ────┼────────┘       │                                      │
│ fracta list  (CLI)      │                │  Gateway (:8080)                     │
│ fracta say   (CLI)      │                │    MCP tool proxy (Elastic, Vendor)  │
│                       │                │    Knowledge graph (FalkorDB)        │
└───────────────────────┘                │    Strategy engine (Python DAGs)     │
                                         │    Tool discovery                    │
                                         └──────────────────────────────────────┘
                                                         │
                                                         │ spawns
                                                         v
                                         ┌──────────────────────────┐
                                         │ Agent (subprocess or pod) │
                                         │   Claude / Codex / OCode │
                                         │   connects to gateway    │
                                         │   via HTTP MCP           │
                                         └──────────────────────────┘

The thin-client boundary is the key insight: whether the control plane runs as a local daemon, a Docker container, or a Kubernetes pod, the client side is identical. Only the infrastructure behind the HTTP API changes.

How Your AI CLI Connects to Fracta

Each runtime reads its MCP server config from a specific file:

Runtime	Config file	Config key
Claude	`.mcp.json`	`mcpServers.fracta`
Codex	`.codex/config.toml`	`[mcp_servers.fracta]`
OpenCode	`opencode.json`	`mcp.fracta`

All three point to the same command: bin/fracta serve --config <path>. The config path determines which deployment mode the thin client connects to. Each scaffold (fracta init --scaffold <mode>) materializes the deployment artifacts you’ll edit (fracta.yaml, deployment/). The runtime CLI configuration that wires fracta into Claude / Codex / OpenCode lives at the project root (.mcp.json for Claude, .codex/config.toml for Codex, opencode.json for OpenCode). The simplest version of those configs runs fracta serve from the project root:

// .mcp.json (for Claude Code)
{
  "mcpServers": {
    "fracta": {
      "command": "fracta",
      "args": ["serve"]
    }
  }
}

# .codex/config.toml
[mcp_servers.fracta]
command = "fracta"
args = ["serve"]

fracta serve reads ./fracta.yaml from your project root by default, so the same minimal runtime config works regardless of which scaffold you initialized. Wrap the command with your secret manager (op run --, doppler run --, etc.) if you need to inject host-side env vars. After editing, restart your AI CLI (or /mcp in Claude Code) to reconnect.

How Credentials Work

There are two separate credential flows. Confusing them is the most common setup mistake.

1. LLM Runtime Credentials

These authenticate agents to their LLM provider (Bedrock, OpenAI). They are configured in fracta.yaml and resolved at spawn time.

fracta.yaml                    At spawn time              Agent process
┌──────────────────┐         ┌─────────────────┐        ┌────────────────────┐
│ agents:          │         │ Credential      │        │ Claude / Codex /   │
│   agent_runtimes:│ refers  │ Planner         │ injects│ OpenCode           │
│     claude:      ├────────>│ resolves tokens ├───────>│ authenticates to   │
│       bedrock    │         │ from profile    │ env +  │ Bedrock / OpenAI   │
│                  │         │                 │ files  │                    │
└──────────────────┘         └─────────────────┘        └────────────────────┘

Each runtime authenticates differently:

Runtime	LLM Provider	Mechanism	Key config
Claude	Bedrock	`auth_profile: bedrock` — a runtime auth resolver runs a command to get a bearer token, injected via `claude_api_key_helper` into `.fracta/user-settings.json`	Required env: `CLAUDE_CODE_USE_BEDROCK`, `AWS_REGION`
Codex	OpenAI	`OPENAI_API_KEY` env var, from host env or K8s Secret	Set in `agents.agent_runtimes.codex.env`
OpenCode	Bedrock	Bearer token materialized at spawn time, injected as `AWS_BEARER_TOKEN_BEDROCK` env var	`auth_profile: opencode_bedrock` with `bearer_env` binding

Where the token command runs depends on the deployment mode:

Local process: on your machine (e.g. bedrock-auth-helper)
Docker Compose / K8s: inside the container/pod (e.g. fetch-bedrock-token script calling a corporate proxy)

For the full credential pipeline reference, see credential-pipeline.md.

2. MCP Server API Credentials

These authenticate MCP backend tools (Elasticsearch, VendorSecurity, etc.) to their external APIs. They are completely separate from LLM credentials. The injection pattern differs by deployment mode:

Mode              How MCP server creds are injected
──────────────    ──────────────────────────────────────────────────────────────

Local process     op run --env-file .op-env -- bin/fracta serve ...
                  1Password resolves op:// refs into env vars
                  fracta.yaml interpolates ${ELASTIC_URL}, ${ELASTIC_API_KEY}
                  Gateway passes env to MCP backend subprocesses

Docker Compose    op run --env-file .op-env -- docker compose up
                  1Password resolves → host env vars
                  docker-compose.yml interpolates ${VAR} into container env
                  MCP backend containers read env vars directly

Kubernetes        make k8s-secrets  (creates K8s Secrets from 1Password)
                  Secrets mounted as env vars in MCP backend pods

The key variables:

Variable	Used by	Purpose
`ELASTIC_URL`	elastic-mcp	Elasticsearch cluster URL
`ELASTIC_API_KEY`	elastic-mcp	Elasticsearch API key
`VENDOR_MCP_CONSOLE_BASE_URL`	vendor-mcp	VendorSecurity console URL
`VENDOR_MCP_CONSOLE_TOKEN`	vendor-mcp	VendorSecurity API token

Any secret injector that sets environment variables works: op run, doppler run, vault exec, or plain export. The repo defaults to 1Password (op) but nothing in fracta requires it. Without MCP server credentials, agents still get graph tools, strategy tools, and fracta lifecycle tools — they just can’t query Elasticsearch or VendorSecurity.

Deployment Modes

Fracta runs in three modes. All share the thin-client architecture above.

                      Local Process     Docker Compose      Kubernetes
                      ─────────────     ──────────────      ──────────
Complexity            Lowest            Medium              Highest
Setup time            ~10 min           ~15 min             ~20 min

Agents run as         Subprocesses      Container procs     K8s Jobs
State store           SQLite            Postgres            Postgres
Workspace type        Git worktrees     Directories         Directories
Queue                 In-memory         Postgres            Postgres

Prerequisites         Go, Docker*       Go, Docker          Go, Docker, kubectl
                      Runtime CLIs**    Compose V2          Local K8s cluster

Best for              Daily dev         Full-stack test     Prod-like test
                      Quick iteration   Team sharing        K8s Job isolation

* Docker is only needed for FalkorDB in local-process mode. ** Runtime CLIs (claude, codex, opencode) are needed on the host for local-process mode. In Compose/K8s the container image bundles them.

Which mode should I use?

Start here
    │
    ├─ Just want to try  fracta quickly?
    │  └──> Local Process (quickstart-local-process.md)
    │
    ├─ Want the full multi-service stack without K8s?
    │  └──> Docker Compose (quickstart-docker-compose.md)
    │
    └─ Need K8s Job isolation or testing K8s deployment?
       └──> Kubernetes (quickstart-kubernetes.md)

For detailed architecture and configuration of each mode, see deployment-modes.md.

Prerequisites

Prerequisite	Local Process	Docker Compose	Kubernetes
Go 1.25+	Yes	Yes	Yes
Docker	For FalkorDB	Yes (with Compose V2)	Yes
kubectl	No	No	Yes
Local K8s cluster	No	No	Yes
`op` CLI (1Password)	Optional	Optional	Optional
Runtime CLI (claude/codex/opencode)	Yes (on host)	No (in container)	No (in container)

Quickstarts

Follow these in order of complexity:

Local Process Quickstart — Build fracta, start FalkorDB, spawn your first agent. Everything runs on your machine. (~10 min)
Docker Compose Quickstart — Build the Docker image, start 7 services, spawn agents through the compose stack. (~15 min)
Kubernetes Quickstart — Deploy to a local K8s cluster, spawn agents as K8s Jobs. (~20 min)

Reference Documentation

Once you’re up and running, these references cover the full depth:

Doc	What it covers
Deployment Modes	Architecture, config, and comparison for all three modes
Runtime Configuration	Claude, Codex, OpenCode adapter setup and K8s deployment
Credential Pipeline	Auth profiles, resolvers, bindings, and the three-layer model
Strategies	Python DAG pipelines for reusable investigation techniques
Contracts & Bindings	Strategy data requirements and MCP data source mapping
Local K8s Guide	Complete K8s runbook with troubleshooting
Event Bus	Internal event architecture
Logging	Structured JSON logging via fractalog

Glossary

Term	Definition
Control plane	The server that owns agent lifecycle: spawn, kill, queue, state, reaper
Gateway	HTTP MCP server that proxies backend tools (Elastic, Vendor) and provides graph/strategy tools to agents
Thin client	`fracta serve` running on your machine — a lightweight stdio-to-HTTP bridge
MCP	Model Context Protocol — the standard for connecting AI tools to LLM runtimes
Runtime	An LLM CLI adapter (Claude, Codex, OpenCode) that fracta can spawn agents with
Adapter	The Go implementation that translates fracta operations into runtime-specific commands
Auth profile	A named credential configuration under `auth.credentials.profiles` in fracta.yaml
Binding	How a resolved credential is delivered to the agent (env var, file, settings.json helper)
Strategy	A reusable Python DAG pipeline that fetches data via MCP, transforms it, and produces findings
Reaper	Background process that cleans up stale/completed agents

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Getting Started with Fracta

Architecture at a Glance

How Your AI CLI Connects to Fracta

How Credentials Work

1. LLM Runtime Credentials

2. MCP Server API Credentials

Deployment Modes

Which mode should I use?

Prerequisites

Quickstarts

Reference Documentation

Glossary

​Architecture at a Glance

​How Your AI CLI Connects to Fracta

​How Credentials Work

​1. LLM Runtime Credentials

​2. MCP Server API Credentials

​Deployment Modes

​Which mode should I use?

​Prerequisites

​Quickstarts

​Reference Documentation

​Glossary

Architecture at a Glance

How Your AI CLI Connects to Fracta

How Credentials Work

1. LLM Runtime Credentials

2. MCP Server API Credentials

Deployment Modes

Which mode should I use?

Prerequisites

Quickstarts

Reference Documentation

Glossary