Quickstart, Docker Compose Mode

Docker Compose runs the full fracta stack in containers: control plane, gateway, strategy runner, Postgres, FalkorDB. Your machine runs only a thin client. MCP backend servers (Elastic, Vendor, your own) are added by extending the scaffolded compose file.

Your machine                         Docker Compose stack
┌──────────────────┐                ┌──────────────────────────┐
│ Claude / Codex / │                │ controlplane    (:19090) │
│ OpenCode         │                │ gateway         (:8080)  │
│   └─ fracta serve ─┼──── HTTP ────>│ strategy-runner          │
│                  │                │ postgres        (:5432)  │
│ fracta spawn (CLI)│                │ falkordb       (:16379)  │
│ fracta list  (CLI)│                │ + your MCP backends      │
└──────────────────┘                └──────────────────────────┘

Prerequisites

fracta CLI installed and on PATH (fracta --help works). See installation.
Docker with Compose V2 — docker compose version.
A git repository to scaffold into. fracta init runs in your own project root.

You do not need runtime CLIs (claude, codex, opencode) installed on your host — they’re bundled in the fracta image.

1. Initialize fracta in your project

From the root of any git repository:

fracta init --scaffold docker-compose

You’ll see:

Fracta initialized successfully.
  scaffold: docker-compose
  source:   embedded (fracta vX.Y.Z)
  files:    N written, 0 skipped

This drops the docker-compose scaffold:

your-project/
├── fracta.yaml                              # thin-client config
├── .fracta/                                 # gitignored runtime state (logs)
└── deployment/
    ├── docker-compose.yml                   # full stack: falkordb, postgres, controlplane, gateway, strategy-runner
    ├── configs/
    │   ├── controlplane.yaml                # server-side config inside the controlplane container
    │   └── gateway.yaml                     # gateway config
    └── auth-helpers/
        ├── README.md
        └── fetch-token-example              # 0755 generic helper template; edit before use

fracta.yaml and everything under deployment/ are yours to edit.

2. Set up auth helpers

The scaffolded deployment/auth-helpers/fetch-token-example is a deliberately non-functional template that fails loudly until you edit it. Open the file — its header comments include reference snippets for AWS Bedrock STS, Vertex AI via gcloud, mounted Anthropic API keys, and custom HTTP token proxies. Pick the one matching your provider. For example, for AWS Bedrock STS:

cat > deployment/auth-helpers/fetch-bedrock-token <<'EOF'
#!/bin/sh
exec aws bedrock get-bearer-token \
  --region "${AWS_REGION:-us-east-1}" \
  --query 'token' --output text
EOF
chmod +x deployment/auth-helpers/fetch-bedrock-token

Update deployment/configs/controlplane.yaml to reference your helper. The default scaffold ships an example profile pointing at fetch-token-example; replace it with a bedrock profile (or whatever name fits) pointing at your script. See the credential pipeline guide for the full profile schema. The compose file bind-mounts ./deployment/auth-helpers/ into every fracta service container at /opt/fracta/auth-helpers/, so resolver command: references find your helpers on PATH inside the container.

3. Start the stack

docker compose -f deployment/docker-compose.yml up -d

Verify all services are healthy:

docker compose -f deployment/docker-compose.yml ps

You should see five services running: falkordb, postgres, controlplane, gateway, strategy-runner.

Secret injection

Compose interpolates ${VAR} from your environment, so any secret manager that sets env vars works. For 1Password:

op run --env-file .op-env -- docker compose -f deployment/docker-compose.yml up -d

For Doppler:

doppler run -- docker compose -f deployment/docker-compose.yml up -d

Use this for any host-side secrets the compose stack needs (database passwords, API keys for MCP backends you add, etc.).

4. Wire fracta into your AI CLI

The scaffolded fracta.yaml points at http://localhost:19090 — the host-mapped port for the compose controlplane container. Your AI CLI runs fracta serve from your project root, which reads ./fracta.yaml. Claude Code (.mcp.json at the project root):

{
  "mcpServers": {
    "fracta": {
      "command": "fracta",
      "args": ["serve"]
    }
  }
}

Codex (.codex/config.toml):

[mcp_servers.fracta]
command = "fracta"
args = ["serve"]

If you need to inject secrets into the host-side fracta serve, wrap it the same way you wrap docker compose up.

5. Connect and verify

Restart Claude Code or run /mcp to reconnect MCP servers. The thin client connects to localhost:19090. You should see fracta tools: fracta_spawn, fracta_list, graph_query, etc. If you’ve added MCP backend services to deployment/docker-compose.yml, you’ll also see their tools.

6. Spawn your first agent

From the CLI:

fracta spawn \
  --task hello-compose \
  --contract "Say hello and list what MCP tools you can see"

From within Claude Code (via MCP):

fracta_spawn(task="hello-compose", contract="Say hello and list what MCP tools you can see")

Check status and output:

fracta list
fracta peek --name hello-compose

Or via MCP: fracta_list() and fracta_peek(name="hello-compose"). Note: Docker Compose uses DirectoryWorkspace, not git worktrees. Agents work in directories under /workspace/agents/<task>. Git merge semantics are not available — for git-based workflows, use local process mode.

7. View logs

docker compose -f deployment/docker-compose.yml logs                   # tail all
docker compose -f deployment/docker-compose.yml logs controlplane      # specific service
docker compose -f deployment/docker-compose.yml logs gateway

8. Stop and clean up

docker compose -f deployment/docker-compose.yml down

To also remove persistent volumes (Postgres data, FalkorDB data):

docker compose -f deployment/docker-compose.yml down -v

Adding MCP backend services

The scaffolded deployment/docker-compose.yml ships only the fracta core. Add MCP backend services by editing the compose file. For example, to add Elasticsearch MCP:

services:
  # ...existing services...

  elastic-mcp:
    image: docker.elastic.co/mcp/elasticsearch:latest
    command: ["http", "--address", "0.0.0.0:8000", "--sse"]
    environment:
      ES_URL: "${ELASTIC_URL}"
      ES_API_KEY: "${ELASTIC_API_KEY}"

Then reference it from deployment/configs/gateway.yaml:

mcp_servers:
  servers:
    elastic:
      remote:
        url: http://elastic-mcp:8000/mcp
        transport: streamable-http

Restart the gateway container to pick up the change:

docker compose -f deployment/docker-compose.yml restart gateway

What differs from local process

	Local Process	Docker Compose
Control plane	Host daemon (:9090)	Container (:19090 on host)
Gateway	Daemon subprocess (:8080)	Container (:8080)
State	SQLite	Postgres
Queue	In-memory	Postgres
Agents	Host subprocesses	Container subprocesses
Workspace	Git worktrees	Directories (no git merge)
MCP backends	Host subprocesses	Container HTTP
LLM auth	Host command (resolved on host PATH)	Container command (resolved at `/opt/fracta/auth-helpers/`)
Secret injection	Wraps `fracta serve`	Wraps `docker compose up`

The client attachment is identical: both use RemoteControlPlaneClient over HTTP.

Strategy runner gateway plumbing

Strategies that call MCP tools inline (ctx.mcp.call_tool(...)) require gateway access from the runner. Since v0.5.2 the Compose scaffold ships this wired by default:

deployment/configs/gateway.yaml declares strategy.gateway_access: true — so strategy_run invocations include the gateway URL and the calling agent’s task in the per-request payload.
The strategy-runner service in deployment/docker-compose.yml boots with --gateway-url http://gateway:8080 --agent-task default, providing a fallback gateway connection for strategies that need one before any per-request URL arrives.

If you author a strategy that calls ctx.mcp.call_tool(), declare it in contract.yaml:

requires:
  graph: true
  mcp: true   # runner refuses to start if ctx.mcp would be None

Next steps

Full architecture reference: deployment overview (Section 2)
Multi-runtime setup: runtime configuration
Auth pipeline deep dive: credential pipeline
Ready for Kubernetes? Try Kubernetes Quickstart

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Quickstart, Docker Compose Mode

Prerequisites

1. Initialize fracta in your project

2. Set up auth helpers

3. Start the stack

Secret injection

4. Wire fracta into your AI CLI

5. Connect and verify

6. Spawn your first agent

7. View logs

8. Stop and clean up

Adding MCP backend services

What differs from local process

Strategy runner gateway plumbing

Next steps

​Prerequisites

​1. Initialize fracta in your project

​2. Set up auth helpers

​3. Start the stack

​Secret injection

​4. Wire fracta into your AI CLI

​5. Connect and verify

​6. Spawn your first agent

​7. View logs

​8. Stop and clean up

​Adding MCP backend services

​What differs from local process

​Strategy runner gateway plumbing

​Next steps

Prerequisites

1. Initialize fracta in your project

2. Set up auth helpers

3. Start the stack

Secret injection

4. Wire fracta into your AI CLI

5. Connect and verify

6. Spawn your first agent

7. View logs

8. Stop and clean up

Adding MCP backend services

What differs from local process

Strategy runner gateway plumbing

Next steps