# Code and Its Runtime Should Travel Together > README files drift, and agents burn tokens reverse-engineering project setup. This article explores a pattern where the runtime environment itself lives and travels with the project repo, versioned and reviewed alongside its code. Source: https://flox.dev/blog/code-and-its-runtime-should-travel-together/ Author: Steve Swoyer Published: 2026-10-29 ## Summary Setup instructions drift out of date, and agents burn tokens reverse-engineering what a README leaves out. A better starting point is to make the runtime environment itself a project asset: a declarative Flox environment, committed to the repo, that defines the packages, config, services, and setup a project needs, pinning every dependency in a lockfile. Anyone (or anything) cloning the repo runs **`flox activate`** and gets right to work. For existing repos, the **`floxify`** skill automatically creates that environment for you. Key takeaways: - README files and static documentation aren't an authoritative definition of what a repo needs to build and run. - A Flox environment's manifest declares packages, settings, hooks, and services; its lockfile pins every resolved dependency. Both live in **`.flox/`** and are versioned with Git. - Environment changes go through the same pull requests, review, CI, and reverts as the code they build and run. - Flox environments run on bare metal, so teams standardize a project's requirements without standardizing everyone's machine. - The **`floxify`** skill inventories an existing repo's dependencies, creates a Flox environment, and verifies the project builds and runs in it. 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. ![A step chart over commits 1 to 40. The code's requirements change four times while the README stays as written at commit 1, leaving a growing gap of undocumented drift. A second chart shows the .flox/ environment changing in the same commits as the code, so every clone runs flox activate.](https://flox.dev/images/blog/01-readme-drift-vs-committed-env.svg) 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 a new project contributor 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. ![A pull request that adds psycopg to a Python file and adds postgresql to .flox/env/manifest.toml, with the lockfile regenerated. The change moves through review, CI that activates the environment pinned at that commit, and merge. git revert restores code and runtime together.](https://flox.dev/images/blog/02-one-pr-code-and-runtime.svg) 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. ![Two timelines on the same scale. Without a committed environment, each contributor clones the repo and reconstructs the setup before working. With a committed Flox environment, an agent runs floxify once and commits .flox/, and each later contributor clones, runs flox activate, and starts work.](https://flox.dev/images/blog/04-reverse-engineer-once.svg) 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. ![A cross-section of a repo in five layers: package manifests, build files, CI workflows, scripts, and container files. Each yields a requirement that maps to a line in one Flox manifest, which then passes resolve, activate, build, run, and test before the repo is floxified.](https://flox.dev/images/blog/03-floxify-repo-archaeology.svg) Crucially, **`floxify`** checks the manifest against the requirements it discovers, verifies that all dependencies resolve correctly, and tests 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 ### If the code is already in Git, why isn't the project reproducible? 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. ### Don't package-manager lockfiles already solve this problem? 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. ### Why keep the environment in the same repository as the code? 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. ### Does standardizing development environments mean everyone has to use the same setup? 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. ### Why does this matter beyond onboarding new hires? 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. ### Can we adopt this pattern without rebuilding our existing projects? 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. ### Does this mean replacing containers or changing our CI/CD pipeline? Not necessarily. Flox can provide the 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 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. ### What happens when the project's dependencies change? 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. --- This is the Markdown version of https://flox.dev/blog/code-and-its-runtime-should-travel-together/. An index of everything on flox.dev is at https://flox.dev/llms.txt, and reference documentation is at https://flox.dev/docs/llms.txt.