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