Skip to main content
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

Check your Go version:

​
Build the binary

The canonical build command:
This is equivalent to:
Output lands at bin/fracta. From the repo root, you can run it directly:
For a system-wide 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:
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:
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:
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:
To verify it runs:
For multi-arch builds (used by the release workflow for ghcr.io publishing), see Releasing.

​
Build artifacts

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.