An edge agent that runs perfectly on the Jetson it was built on, then needs a full rebuild the moment the fleet adds a Coral board, is not a portable agent. It is a monolith with a demo. The 12-factor methodology — originally written for cloud web services — turns out to be exactly the discipline that keeps an agent reproducible when the hardware underneath it keeps changing. The single most important claim to internalise: on edge computer vision, portability is not a feature you add later, it is a property of how you structure config, state, and backing services from the first commit. The confusion starts because “agent” and “edge” both invite the monolith. You have a box, you have a model, you have some orchestration logic that decides what to do with a detection, and the path of least resistance is to bake all of it into one image that ships to that box. It works on the bench. It works in the first pilot. Then someone changes the camera, or the fleet grows past a handful of identical units, or the supply chain swaps the accelerator, and every hidden assumption you baked into that image surfaces at once — per device. What does “12-factor agents” actually mean for something running on a device? The original 12-factor methodology was a set of rules for building web apps that deploy cleanly to a platform: store config in the environment, treat backing services as attached resources, run the app as stateless processes, keep development and production as similar as possible. None of those rules mention machine learning, and none of them mention hardware. That is the point. They are structural constraints on where things live, not on what the application does. Applied to an edge AI agent, the factors that carry the most weight are the ones that separate the parts of the system that change on different schedules. Your control logic — the code that decides “on a detection above threshold X, do Y” — changes slowly and should be identical everywhere. Your model weights change when you retrain. Your config — thresholds, camera parameters, which accelerator runtime to target — changes per device and per deployment. A 12-factor agent keeps those three on separate tracks so a change to one does not force a rebuild of the others. The divergence from the naive approach shows up at exactly one moment: the first hardware change. A monolithic agent bakes config, weights, and logic into one image built for one target. Swap the target and you rebuild and re-tune from scratch. A 12-factor agent swaps the model artifact or the backing service — the inference runtime, the model store — without touching the control logic. This is the mechanism behind the ROI: a model or config change ships as a versioned artifact rather than a per-device rebuild. How the factors map from a cloud web service to an edge agent Not every factor translates one-to-one. Some map cleanly, some need reinterpretation for a device with no reliable network, and one or two barely apply. Reading the table below matters more than memorising twelve rules, because it tells you which factors are load-bearing on the edge and which are cloud-specific. Factor Cloud meaning Edge-agent translation Load-bearing on edge? Config in environment No config in code Thresholds, runtime target, camera params injected, never baked High — this is the portability lever Backing services as attached resources DB/queue swappable by URL Inference runtime, model store, telemetry sink swappable by reference High Stateless processes No sticky in-process state Agent holds no unrecoverable state; restart is safe High — enables safe rollback Dev/prod parity Same stack dev and prod Same container across bench and fleet; hardware differs, image does not High Build/release/run separation Distinct stages Model + config compose a versioned release; run picks it up per device High Logs as event streams Stdout, not files Telemetry streamed out, not accumulated on a full flash disk Medium Disposability Fast startup/shutdown Agent survives power loss and cold-boots to a known state Medium Port binding / concurrency Self-contained service, scale by process Weak fit — edge scales across devices, not processes on one box Low The factors that earn their place on the edge are the ones that decouple the slow-changing control logic from the fast-changing model and the per-device config. The cloud-specific concurrency and port-binding factors mostly do not, because an edge fleet scales horizontally across heterogeneous boxes rather than vertically inside one. Which factors matter most for portability across Jetson, Coral, and Neural Compute Stick? If you are running the same agent on an NVIDIA Jetson today and an edge TPU like Google Coral tomorrow — with an Intel Neural Compute Stick somewhere in the fleet for good measure — three factors do almost all the work. First, config as an explicit, injected resource. The runtime target is config, not code. A Jetson wants TensorRT; a Coral wants a TFLite model compiled for its Edge TPU; the Neural Compute Stick wants OpenVINO. If the agent reads “which runtime am I on” from the environment and loads the matching backing service, the same control logic runs on all three. Bake the runtime choice into the image and you now maintain three images that drift apart. The number of distinct device-specific images a fleet must maintain is the metric that tells you whether you got this right — a 12-factor fleet trends toward one image plus N configs; a monolithic fleet trends toward N images (observed pattern across edge deployments; not a benchmarked rate). Second, backing services as attached resources. The model is not part of the agent — it is a resource the agent attaches to. That is what lets you ship a Jetson-compiled and a Coral-compiled build of the same model as two artifacts, selected by config, without the agent knowing or caring which one it loaded. The same principle applies to the model store, the telemetry sink, and any remote coordination service. Third, statelessness. An agent that accumulates state in-process — a running tally, a cached calibration, a half-finished batch — cannot be safely restarted, and cannot be safely moved to a different box. Keep the recoverable state in an attached resource and the process itself becomes disposable. That disposability is what shortens the rollback window: if an update regresses latency or accuracy, you roll the release reference back and restart, rather than reconstructing device state by hand. These same portability concerns are why runtime choice deserves its own analysis; our write-up on compiler flags for cross-platform ONNX and CoreML inference covers the layer directly beneath the backing-service abstraction, where the model actually gets compiled for each target. Do 12-factor principles help or fight the edge latency/accuracy/power trade-off? This is the fair objection: edge CV is already a constant negotiation between latency, accuracy, and power per device. Does adding deployment discipline add overhead that eats into a budget you cannot spare? At runtime, no. The factors are structural — they govern how config and artifacts are organised, not how many FLOPs the model burns. A stateless process on a Jetson runs the same inference as a stateful one; it just does not hoard state between frames. Treating config as injected costs a few environment reads at startup, not per-frame latency. The overhead is at build and release time, where you spend effort composing versioned releases instead of hand-tuning images — and that effort is what you were paying anyway, just spread invisibly across every manual deploy. Where the factors actively help the trade-off is characterisation. When each device’s accuracy-for-latency operating point is set by explicit, versioned config rather than hand-tuning, the trade-off stays measured per target instead of drifting silently after each deploy. You can compare the same release across a Jetson and a Coral and know that any difference is hardware, not a config someone tweaked and forgot. That reproducibility is the foundation of any honest cross-hardware latency comparison — the kind we walk through when weighing where a DGX Spark fits in the edge CV latency and cost trade-off against constrained accelerators. What does a non-12-factor edge agent look like when the fleet grows? The failure mode is quiet at first. One device, one image, everything hand-tuned — it works, and it looks efficient because there was no ceremony. The cracks appear on the second axis of change: more devices, or different hardware. Config baked into the image means every threshold change is a rebuild-and-reflash across the whole fleet, and no two devices are provably running the same logic. State leaking into the process means a crash or power loss on a remote box needs a physical visit or a bespoke recovery script, because restart does not restore a known state. The model welded to the agent means retraining forces a full agent release, and porting to a new accelerator means forking the whole thing. No dev/prod parity means the bench setup and the field setup diverge, and bugs that only appear in the field cannot be reproduced where you can debug them. Each of these is survivable on one device. Multiply across a fleet and they compound: the monolith needs a rebuild and a re-tune per target, and the fleet fragments into device-specific images that drift apart until nobody can say what any given box is actually running. That fragmentation is the concrete cost the discipline exists to prevent. How do I audit an existing edge agent against 12-factor principles? Before signing off a fleet deployment, run the agent through a short diagnostic. Each “no” is a portability liability that will surface at the next hardware change. Can you change a threshold without rebuilding the image? If not, config is not externalised. Can you swap the inference runtime by changing config alone? If not, the backing service is not attached — it is welded in. Can you kill and restart the agent on any device and reach a known-good state? If not, the process is stateful. Is the image bit-identical across bench and field, with only config differing? If not, you have no dev/prod parity. Do a model version and a config version compose an addressable release you can roll back to? If not, build/release/run are conflated. How many distinct images does the fleet maintain today? More than one plus per-target compiled model artifacts is a fragmentation signal. Portability and statelessness are exactly the dimensions a production readiness review checks before a fleet edge deployment is signed off — the same discipline our computer vision consulting practice applies when scoping an edge rollout, and the kind of trade-off scoping covered in what a computer vision consultant does. FAQ What does working with 12 factor agents involve in practice? The 12-factor methodology is a set of structural rules about where config, state, and dependencies live — config in the environment, backing services as attached resources, processes stateless — rather than what the application computes. Applied to an agent, it means the control logic, the model weights, and the per-device config change on separate tracks, so a change to one does not force a rebuild of the others. In practice this is what makes an agent reproducible when the hardware underneath it keeps changing. How do the 12 factors map to an AI agent running on edge devices rather than a cloud web service? Most factors translate, but their weight shifts. Config-in-environment, backing-services-as-attached-resources, statelessness, dev/prod parity, and build/release/run separation are load-bearing on the edge because they decouple slow-changing control logic from fast-changing models and per-device config. Cloud-specific factors like port binding and process concurrency barely apply, because an edge fleet scales horizontally across heterogeneous boxes rather than vertically inside one. Which factors matter most for portability across heterogeneous edge hardware like Jetson, Coral, and Neural Compute Stick? Three do almost all the work: config as an explicit injected resource (so the runtime target — TensorRT, Edge TPU TFLite, or OpenVINO — is chosen by config, not baked in), backing services as attached resources (so the model is a resource the agent attaches to, not part of it), and statelessness (so the process is disposable and portable). Get these right and a fleet trends toward one image plus N configs instead of N drifting images. How does keeping an agent stateless and treating config as explicit help reproducibility when the same agent runs on different edge targets? Explicit config means each device’s operating point is set by a versioned value, not hand-tuning, so the same release run on a Jetson and a Coral differs only by hardware — not by a config someone changed and forgot. Statelessness means the process can be killed and restarted to a known state, which is what makes rollback fast and cross-device moves safe. Together they keep the accuracy-for-latency trade-off characterised per target instead of drifting after each deploy. How do 12-factor principles interact with the edge latency/accuracy/power trade-off — do they help or add overhead? At runtime they add essentially no overhead: the factors govern how config and artifacts are organised, not how many FLOPs the model burns. The cost is at build and release time, composing versioned releases instead of hand-tuning images — effort you were already spending, just spread invisibly across manual deploys. They actively help the trade-off by keeping each device’s operating point measured and reproducible rather than silently drifting. What does a non-12-factor edge agent look like, and where does it break down as a fleet grows or hardware changes? It is a single image with config, model weights, and control logic all baked in, hand-tuned for one box. It works on one device and looks efficient. It breaks at the first hardware change or fleet update: threshold changes become full reflashes, crashes need physical recovery, retraining forces a whole agent release, and the fleet fragments into device-specific images that drift until nobody can say what any box is running. How do I audit an existing edge agent against 12-factor principles before a production deployment? Run a short diagnostic: can you change a threshold without a rebuild, swap the runtime by config alone, restart on any device to a known state, keep the image bit-identical across bench and field, and roll back an addressable model-plus-config release? Then count how many distinct images the fleet maintains — more than one plus per-target compiled model artifacts is a fragmentation signal. Each “no” is a portability liability that surfaces at the next hardware change. The open question the discipline leaves you with is not whether to apply the factors, but which ones your fleet’s next change will actually test. Portability is only ever proven at the boundary between two hardware targets — so the honest way to close an edge deployment is to name the target you have not run on yet, and ask which factor breaks when you do.
