Genesis

Rebuild developer environments from a versioned configuration: tools, runtimes, repositories, environment variables, and setup scripts. Genesis is written in Go and builds into a standalone binary. Local provisioning is the current focus; cloud services and complete environment restoration remain unfinished.

go build -trimpath -o bin/genesis ./apps/cli
./bin/genesis --help

Go 1.27 or newer builds the source; use a supported Go release for production. The resulting binary needs no language runtime. Cross builds cover macOS, Linux, and Windows on amd64 and arm64. Native installer support varies by plugin.

tools:
  - type: node
    version: "22"
    use_nvm: false
  - type: git
languages:
  - type: go
    version: "1.22.5"
repositories:
  - url: https://github.com/example/project.git
    folder: project
scripts:
  - name: verify
    command: git --version
    when: after
env:
  PROJECT_ROOT: "${HOME}/projects"

From the environment directory, run the built binary by its absolute path:

/path/to/genesis/bin/genesis apply --dry-run --json
/path/to/genesis/bin/genesis apply
/path/to/genesis/bin/genesis doctor

apply --config path.yml selects an explicit config. --parallel 4 enables bounded goroutines for independent plugins; the default remains sequential. Dependencies, overlapping installation paths, and shared ports constrain parallelism. --timeout 15m bounds configuration and environment work, including scripts and downloads; completed changes are retained on cancellation. System package prerequisites are deduplicated before plugin apply. Failed dependencies block dependent plugins. Scripts and repositories run in configured order; repository reapply preserves existing work and checks origin, branch, and repository root before accepting an existing destination.

All eleven builtins remain: Node, Bun, Deno, pnpm, Yarn, Python, Go, Java, Git, Docker, and Homebrew. Archive installers verify published SHA256 checksums, stage and verify installations, and retain recoverable backups when rollback fails. Linux shared tasks support APT, DNF, pacman, and APK; Docker official repositories support Ubuntu, Debian, Fedora, CentOS, and RHEL. Docker Desktop and unavailable Windows tools report manual setup requirements.

YAML is the portable default. Executable Go configurations emit JSON; compiled Go plugins and executable plugins replace runtime module imports. See configuration and plugin development.

Only run trusted configurations and plugins. Dry-run skips provisioning hooks; Go configs and external plugin validation still execute configured code. Installers modify the host. System package operations have no general rollback.

go test ./...
go test -race ./...
go vet ./...
bun run --cwd apps/docs build
bun run --cwd apps/docs dev
go run ./scripts/release

Source layout: apps/cli, apps/docs, packages/core, packages/plugins, packages/extension, and scripts. One Go module replaces workspace build orchestration. Documentation stays independent in apps/docs, using VitePress. Run cd apps/docs && bun install --frozen-lockfile once, then bun run dev or bun run build from that directory. Its JS dependencies belong only to docs.

Real downloads and installer reapply checks: go run ./scripts/smoke installers. They use temporary prefixes and need network access plus source-build tools for Git. Linux package/Docker smoke modes require an explicitly disposable root host. CI exercises three operating systems and Linux distro containers; local cross-compilation is not evidence of native installer execution.

See roadmap and platform support. Cache metadata APIs remain available, but artifact/network restoration, OAuth, and cloud apply are not implemented. Login stores local token metadata without verifying cloud access.