fracta init

Materializes one of three deployment scaffolds (local, docker-compose, k8s) into the current directory. The first invocation drops a complete deployment tree in your project root; re-running with the same scaffold is idempotent. Switching scaffolds in an existing project is refused — see Switching modes below. Only --scaffold local requires the directory to be a git repository (the local backend uses git worktrees to isolate agent runs). --scaffold k8s and --scaffold docker-compose run agents as Kubernetes Jobs or compose services and do not need a .git directory; you can fracta init --scaffold k8s in a fresh empty folder.

Initialize fracta in the current git repository by materializing a scaffold.

Examples:
  fracta init --scaffold local
  fracta init --scaffold docker-compose
  fracta init --scaffold k8s
  fracta init --scaffold k8s --source github:acme/fracta-scaffolds@v3.2.0
  fracta init --scaffold k8s --source ./local/templates
  fracta init --scaffold k8s --source https://example.com/scaffold-k8s.tar.gz \
    --source-checksum sha256:abc123...
  fracta init --scaffold local --force --yes

The first invocation drops a complete deployment tree into the operator's
repository. Re-running with --force overwrites existing files; without
--force, existing files are preserved.

Usage:
  fracta init [flags]

Flags:
      --scaffold string          Scaffold to lay down: local | docker-compose | k8s
      --source string            Override scaffold source (path, github:owner/repo@ref, or https://...)
      --source-checksum string   Optional sha256:<hex> for https:// sources
      --force                    Overwrite existing files
      --yes                      Skip confirmation prompt for --force
  -h, --help                     help for init

Scaffolds

`--scaffold` value	Use when	Produces
`local`	Single-machine development; agents run as host subprocesses	`fracta.yaml` (`runtime.backend: local`), `.fracta/state.db`, `deployment/auth-helpers/`
`docker-compose`	Local containerized stack: controlplane, gateway, postgres, falkordb, strategy-runner	`fracta.yaml` (thin client), `deployment/docker-compose.yml`, `deployment/configs/`, `deployment/auth-helpers/`
`k8s`	Kubernetes deployment; agents as Jobs or stream pods	`fracta.yaml` (`runtime.backend: kubernetes` with `extra_volumes`), `deployment/k8s/manifests/`, `deployment/auth-helpers/`

The local scaffold is the lightest; docker-compose and k8s scaffold a full service topology. See the per-mode guides:

`--source` resolution

`--source` value	Resolves to
(unset)	The scaffold tree baked into your `fracta` binary (offline-by-default)
`./relative/path` or `/abs/path`	Local filesystem; expects `<path>/<kind>/` to exist
`github:owner/repo@ref`	Codeload tarball from `https://codeload.github.com/owner/repo/tar.gz/<ref>`; expects `<repo>/<kind>/`
`https://...tar.gz`	Raw HTTPS tarball; expects `<kind>/` at archive root

Tarball downloads are capped at 50 MB. HTTPS sources accept an optional --source-checksum sha256:<hex> for integrity verification — without it, init prints a warning and proceeds. GitHub refs that don’t look like commit SHAs (anything not matching [0-9a-f]{7,}) emit a reproducibility warning to stderr — pin to commit SHAs or release tags for CI/CD.

What gets written

The walker materializes every file in the chosen scaffold tree, skipping existing files by default (so re-running fracta init doesn’t clobber operator edits). Files under any auth-helpers/ directory are always written with mode 0755; everything else preserves the source-reported mode or defaults to 0644. fracta init also:

Verifies the directory is a git repo only for --scaffold local (the local backend uses worktrees). Compose and k8s scaffolds skip this check; they run agents as services / Jobs, so .git is irrelevant.
Checks scaffold-specific dependencies via prereq.EnsureDepsFor(kind): local needs git; docker-compose needs docker + the docker compose plugin; k8s needs kubectl (warns if no current kube-context, doesn’t fail).
Initializes .fracta/state.db (SQLite) for local scaffolds only. Compose and k8s use postgres-backed state in their deployed services.
Appends .fracta/ and .worktrees/ to .gitignore if not already present.

Switching modes

A project that’s already been scaffolded as one mode cannot be re-initialized as another. Spec-42 ships single-mode-per-project: the fracta.yaml, deployment/ tree, and embedded controlplane configs are mode-coupled, so a mixed scaffold would produce a tree where the manifests, configs, and top-level config disagree about what’s running. If you try to switch:

$ fracta init --scaffold k8s
Error: this project is already scaffolded as local; cannot re-init as k8s
without losing customizations.

Resolution paths:

Switch destructively: rm -rf deployment/ fracta.yaml .fracta/ && fracta init --scaffold k8s. Loses any operator edits.
Re-run idempotently: fracta init --scaffold local against an existing local project skips existing files (0 written, N skipped) and refreshes anything missing.
Multi-mode requirements: see the Switching modes section of the deployment overview for separate-repo and separate-worktree patterns.

Conflict policy and `--force`

Default	`--force`
Existing files are preserved (`SkipExisting`)	Existing files are overwritten (`Overwrite`)
Output reports `N written, M skipped`	Prompts `[y/N]` unless `--yes` is passed

--force is destructive and bypasses the mode-mismatch check above only if you rm -rf the relevant directories first. Force-overwriting an existing mode (e.g. --force --scaffold local on a local project) refreshes the template files in place — useful if you want to revert local edits.

Deprecated invocation

$ fracta init                   # no --scaffold flag
warning: 'fracta init' without --scaffold is deprecated; defaulting to
--scaffold local. This will be required in the next release.

The next major release will require --scaffold explicitly. Update scripts and documentation now.

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Scaffolds

`--source` resolution

What gets written

Switching modes

Conflict policy and `--force`

Deprecated invocation

​Scaffolds

​--source resolution

​What gets written

​Switching modes

​Conflict policy and --force

​Deprecated invocation

Scaffolds

`--source` resolution

What gets written

Switching modes

Conflict policy and `--force`

Deprecated invocation