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 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 describes packages, config settings, runtime hooks, setup or teardown automation, and services; its lockfile 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. 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.
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—isn’t the answer: it’s like layering epicycles 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 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 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: 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 and the floxify skill, 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 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.
Keep learning with Flox
Interviews, tips, guides, industry best practices, and news.
Yes We Can: Standardizing Dev Environments without Containers
Is it possible to standardize local development environments without using VMs or containers? You bet. Declarative Flox environments give humans and agents the same locked dependencies, without jailing developers inside a container.
Read postA Turnkey Toolkit for Agentic Development with Flox
Test drive OpenClaw and nearly 80 agentic AI environments on your own machine. At once. Without permanently breaking anything. Share what you build with others and it Just Works. Impossible, you say? Not with Flox!
Read postFocusing on the Code, Not the Cruft
Putting the flox and floxify agent skills through their paces with Claude Code: building a FastAPI embedding service from scratch, then reconstructing a complete six-service Mastodon development environment from an existing checkout.
Read postMaking Flox Better for People and Machines
Flox v1.14.1 improves activation, search, and usability as more developers, CI systems, and AI agents rely on Flox.
Read postFlox Account Tokens for People and Machines
Flox now supports granular, role-based tokens that enable organizations to reduce their blast radius, keep pipelines running smoothly through staff changes, easily rotate credentials on a schedule, and seamlessly authenticate in browserless workflows.
Read postOne Tool, Every Language: Declarative Dev Environments
Imagine creating declarative, reproducible environments for the toolchains and dependencies you use in your workflows. Declaring compilers, debuggers, dev libraries, and other dependencies as code. Declarative patterns make this convenient, reproducible, and scalable.
Read post


