Code and Its Runtime Should Travel Together

Flox, a reproducible-environment tool, argues that a project's runtime should be versioned in Git alongside its code so that both humans and AI agents have an authoritative starting point instead of relying on README files and static documentation. Flox stores a manifest and lockfile in the repo's .flox/ directory, pins all transitive dependencies in an immutable store, and lets engineers run `flox activate` to get identical software on the same OS and CPU architecture; unlike OCI containers, Flox environments can run on bare metal. The article contends that committing environment edits alongside code changes lets runtime updates go through the same pull request and review process, and that agents otherwise waste tokens debugging setup issues or dependency conflicts.

Code and Its Runtime Should Travel Together We've all had the experience of following a project's setup instructions to the letter… only to discover that its README is out of date, critical dependencies aren’t documented or aren't even identified , some of the steps are no longer necessary… or some other requirement, somewhere , isn’t captured. Agentic AI helps with this, but at a cost. Agents can set fire to tokens debugging setup issues or dependency conflicts, sometimes disappearing down rabbit holes that have nothing to do with the work we assigned them. The worst outcome of all is when they lose the plot altogether, mistaking problems unearthed while spelunking or fiddle-faddling https://www.reddit.com/r/ClaudeAI/comments/1sxwhnc/i extracted the full list of claude codes spinner/ for the task they're supposed to perform. The upshot is that humans and agents alike need an authoritative starting point for working in code repos. README files and static documentation aren’t sufficient. This article explores a pattern where the runtime environment itself lives and travels with the project repo, versioned and tracked alongside its code. Make the Runtime Part of the Repo Flox gives teams a way to define the software a project needs as a declarative, reproducible environment. This environment’s manifest https://flox.dev/docs/man/manifest.toml manifest-toml describes packages, config settings, runtime hooks, setup or teardown automation, and services; its lockfile https://flox.dev/docs/concepts/environments manifest-lock pins all pre-resolved software dependencies. Both files live in the project's .flox/ directory and can be versioned and managed using Git. Under its hood, Flox resolves a project's declared packages and their transitive dependencies into a locked dependency graph https://flox.dev/blog/standardized-development-environments-explained/ . Flox materializes those dependencies in an immutable store, so anyone using the same environment on the same OS and CPU architecture gets the same pinned software… anytime or anywhere they activate it. This way, when an engineer clones a repo and runs flox activate , they don't need to traverse an interminable README or task an agent with reverse-engineering its setup just to build and run code. Plus, unlike OCI containers, Flox environments can run on bare metal , so each engineer can keep using her preferred editor and shell, with access to local resources. This gives teams and maintainers a way to standardize a project's requirements without standardizing everyone's machine. Platform teams need only make flox activate an option for every repo, while each team defines their projects’ packages, versions, and services according to their own local standards. Flox is governance with the consent of the governed. Version and Review Runtime Changes Along with Code Changes And because the Flox environment lives alongside the code, keeping both in sync becomes a single, unified workflow. If a feature needs a new package or a version bump, it's a declarative edit to the Flox environment. Commit this edit alongside changes to code, then review, promote, or revert one or both together. That way, changes to an environment go through the same pull request and review process as the code it builds and/or runs. The workflow is familiar: changes show up as diffs; GitHub Actions tests code using runtime dependencies pinned to the same commit; Git history records how the project’s runtime environment changes over time. Reverting a commit restores the previous code and runtime with its locked dependencies. Runtime maintenance becomes an integral part of each team's routine development process. Onboarding Isn’t Just for New Hires An engineer can know her own codebase inside out, but a cross-service bug or feature request can pull her into a repo that’s maintained by another team. When this happens she often has no idea how to build and run this service. Sure, she can turn a swarm of agents loose on the problem. And maybe this swarm figures everything out. But this works for a single checkout on a single machine at a specific point in time. What about the next engineer who clones the repo? They’ve got to figure it out all over again… and so does the next agent. Throwing more agents at the problem—the agentic equivalent of stigmergy https://en.wikipedia.org/wiki/Stigmergy —isn’t the answer: it’s like layering epicycles https://en.wikipedia.org/wiki/Deferent and epicycle on top of a fundamentally flawed paradigm. Yes, agents can leave a trail of markdown breadcrumbs that document how to set up and run a project. But this isn't the same thing as having a reproducible environment that travels along with project code , resolving the same dependencies across space and time. In point of fact, markdown breadcrumbs are a shoddy substitute for the one thing every repo should have: an authoritative definition of what the code it contains needs to build and run. Flox gives teams and maintainers a way to solve this problem. Define an environment once, commit it with project code, and anyone or anything can run flox activate … instead of reverse-engineering from scratch. And when a project's requirements change, its runtime changes with them. Start with the Repos You've Already Got Most orgs aren't starting with a blank slate. Their existing repos contain clues to build and runtime requirements, but these are scattered across build files, scripts, and CI workflows. Flox's floxify skill https://github.com/flox/flox-skills gives AI coding agents a systematic way to reconstruct these requirements. It inspects an existing repo, inventories its dependencies, and creates a Flox environment to reproduce them. Package manifests only tell part of the story. floxify performs archaeology, digging through the whole of the repo for dependencies and requirements that might otherwise reveal themselves only when something fails to build or run. Crucially, floxify checks the manifest against the requirements it discovers, verifies that all dependencies resolve correctly, and tests activation https://flox.dev/glossary/ activation behavior. The agent uses the environment to build, run, and test project code. Only when the repo successfully builds and runs does the agent bless it as truly floxified . For new projects, a companion flox skill floxifies a project from the start… before there's any archaeology to excavate. Just tell the agent s what you're building, flox works out which dependencies, config, or services your project needs. This gives you a reproducible Flox environment from the get go. Working in a repo never becomes a redux of Groundhog Day https://www.imdb.com/title/tt0107048/ : the agent reverse-engineers the repo once , up front. From then on, anyone or anything can clone the repo, activate its Flox environment, and get straight to work. Make Every Contributor's Job Easier Pick a repo your team maintains, or one you need to contribute to. Try Flox https://flox.dev/download/ and the floxify skill https://github.com/flox/flox-skills , then review and commit the resultant environment. Give every engineer or agent a repo that builds and runs at any time, in any place... rather than a requirements reverse-engineering project. Frequently Asked Questions Git records your source code, but it doesn't capture the software installed on the machine that last built or ran it. And even the most carefully written setup instructions can produce different results as upstream packages change. Committing a locked Flox environment alongside the code gives you a reproducible definition of the software the project depends on. Only for the dependencies they manage. A language-specific lockfile might pin every library your application imports but say nothing about the compiler, native libraries, or system utilities it depends on. Flox defines and locks the broader software environment. Language-specific package managers and their lockfiles can continue handling the dependencies they own. Because changes to code often require changes to its dependencies. Keeping both in one repo means a pull request can include the application change and the runtime change it requires. Reviewers can examine both, CI can test them together, and Git history preserves the combination that worked. No. The idea is to standardize what a project needs, not dictate how every engineer works. Flox environments run directly on supported Linux and macOS systems, exposing the project's declared dependencies without requiring developers to abandon their preferred editors or local workflows. Different teams can maintain different environments for their projects. Because engineers routinely need to work in repositories they don't own. A production bug might require changes to another team's service; a shared feature might span several codebases. Open source contributors encounter the same problem. Having the runtime travel with the repository means contributors can spend less time reconstructing an unfamiliar setup and more time working on the code. Yes. Flox's floxify skill helps AI coding agents investigate an existing repository, reconstruct its build and runtime requirements, and create a Flox environment. The agent can then use that environment to build and test the project. Review and commit the result, and the investigation becomes a one-time upfront investment rather than work every subsequent contributor must repeat. Not necessarily. Flox can provide the development environment https://flox.dev/glossary/ development-environment directly on an engineer's machine, and GitHub Actions can activate that same locked environment for CI. Teams can also use flox containerize https://flox.dev/docs/man/flox-containerize flox-containerize to generate minimal, distroless OCI images https://flox.dev/glossary/ oci-image from declarative Flox environments, bake Flox environments into OCI images, or otherwise retain their existing container workflows. The important distinction is whether each stage consumes the same locked dependencies or independently assembles its own runtime. Update the Flox environment alongside the code that requires the change. The updated manifest and lockfile go through the ordinary pull-request and CI process. Git preserves the previous environment definition, so teams can return to an earlier locked dependency set if necessary. The environment continues to evolve with the project, instead of becoming another document that gradually falls out of date. Keep learning with Flox Interviews, tips, guides, industry best practices, and news. View all posts https://flox.dev/blog/ Mitigating Shai-Hulud Attacks with Hermetic BuildsShai-Hulud-style supply chain worms exploit the secrets, permissions, and network access exposed during builds. Reproducible, hermetic build environments can limit the blast radius across local development and CI/CD. Read post Training nanoGPT on Slurm with a Nix-Pinned EnvironmentThis article describes a pattern for creating reproducible runtime environments for ML/AI using declared, graph-backed environments based on Nix and Flox. The same Nix and Flox environments run as-is during both model training in local dev to checkpoint validation in eval. Read post A Pattern for Local Dev: Runtime on the Host, Services in ContainersRun project runtimes on your local machine with Nix, Guix, or Flox, let containers handle PostgreSQL, Redis, and other services. Get fast, reproducible local dev that travels from laptop to CI to production ... and back again. Read post Standardized Development Environments ExplainedWorks-on-my-machine is symptomatic of an ongoing failure to treat the local development environment itself as shared project infrastructure. Standardized development environments are a compelling solution to chronic problems of this kind. Read post Achieving CVE Remediation in an Era of Escalating VulnerabilitiesAI is accelerating the rate of CVE discovery. Learn how Flox and Nix transform package vulnerability triage from repeated artifact scans into quick, queryable dependency-graph analysis Read post