Building from source

Local builds, Makefile targets, and version stamping for the Go binary and Python sidecar.

Fracta is a single Go binary plus a Python strategy-runner sidecar. The Go binary is the only thing you need to build for most development work — the Python sidecar runs separately and only matters when you’re testing strategy execution.

Prerequisites

Tool	Minimum	Notes
Go	1.25.x	Declared in go.mod. Newer is fine; older won’t work.
Make	any modern version	Targets are POSIX-compatible bash.
Docker	20+	Only required for make docker-build and the Compose/K8s deployment modes.
uv	latest	Only required if you’re working on Python strategies. Install with brew install uv or see astral.sh/uv.

Check your Go version:

go version
# go version go1.25.5 darwin/arm64   ← matches go.mod

Build the binary

The canonical build command:

make build

This is equivalent to:

go build -o bin/fracta .

Output lands at bin/fracta. From the repo root, you can run it directly:

./bin/fracta --help
./bin/fracta --version    # → "fracta version dev"

For a system-wide install:

make install

(Currently the same as make build. A future iteration may copy to $GOPATH/bin or /usr/local/bin.)

Running the binary in development

Most development happens against the local-process deployment mode (no Docker, no K8s). The fastest loop:

# 1. Build the fracta binary you're working on
make build

# 2. From a separate test project (any git repo), scaffold fracta with your dev binary
mkdir -p /tmp/fracta-dev-project && cd /tmp/fracta-dev-project
git init -q
/path/to/fracta/bin/fracta init --scaffold local

# 3. Use Claude Code (or bin/fracta spawn) to drive the orchestrator from that project

The scaffold materializes fracta.yaml, .fracta/state.db, and deployment/auth-helpers/. Edit fracta.yaml to point at your dev FalkorDB / config / etc.

For full end-to-end setup, see the Local Process Quickstart.

Version stamping

The binary embeds a version string accessible via --version. By default it’s "dev". To stamp a specific version:

go build -ldflags "-X main.version=v0.2.0" -o bin/fracta .
./bin/fracta --version
# → "fracta version v0.2.0"

The main.version variable is defined in main.go and passed to the Cobra root command via cmd.SetVersion(...). The release workflow (see Releasing) injects the git tag here automatically when building tagged versions.

Cross-compilation

Go cross-compiles natively. To produce a Linux ARM64 binary from a Mac:

GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
  go build -trimpath -o bin/fracta-linux-arm64 .

The -trimpath flag is recommended for distributable binaries — it strips local filesystem paths from the binary, making builds reproducible across machines and avoiding leaking developer paths.

CGO_ENABLED=0 produces a fully static binary (no glibc dependency) suitable for distroless and scratch base images. The release workflow uses this combination for all four platform binaries.

Docker build

The Dockerfile is a two-stage build:

1. Stage 1: Go module compiled to /out/fracta
2. Stage 2: node:20-slim base, installs the Claude / Codex / OpenCode CLIs via npm, installs uv for Python deps, copies the strategy directory, sets up the entrypoint script

To build locally:

make docker-build       # → fracta:latest

To verify it runs:

docker run --rm fracta:latest fracta --version

For multi-arch builds (used by the release workflow for ghcr.io publishing), see Releasing.

Build artifacts

Artifact	Produced by	Used by
bin/fracta	make build	Local development, manual testing
fracta:latest (Docker)	make docker-build	Compose mode (make compose-up-op)
fracta/vendor-mcp:latest (Docker)	make vendor-mcp-build	K8s mode (vendor MCP backend pod)
bin/fracta (in-pod)	Stage 1 of Dockerfile	K8s agent pods, Compose containers

bin/ is gitignored — never committed. The release workflow produces dist artifacts attached to GitHub Releases (see Releasing).

Common build issues

undefined: someSymbol after pulling Run go mod download to ensure dependencies match go.sum.

package X is not in std errors Likely a Go version mismatch. Check go version against the version in go.mod.

make: *** missing separator Tabs vs. spaces in the Makefile. The repo uses tabs; some editors silently convert. Reset with git checkout Makefile and re-edit carefully.

Slow go test ./... The first run rebuilds all dependencies; subsequent runs are fast (Go caches packages). To force a clean rebuild: go clean -testcache && go test ./.... To bypass the cache for a single run: go test ./... -count=1.